Check availability for several domains
POST /api/v2/domains/availability
Checks up to 50 domain names in one request. The request field is names, not domains. Without an API key or a client-area login, every name must share the part before the extension (example.se, example.com). When all names share that part and there are at most three extensions, the answer usually comes in the same response with data. That can take up to about 20 seconds, so set your client timeout above that. Names that differ before the extension, more than three extensions, or a check that takes longer return 202 with operation.pollUrl. Poll that URL. It is GET /api/v2/domains/availability/{jobId} with the dcheck_... ID from operation.jobId. Handle both answers. At most 8 extensions are checked per name. Further ones are dropped. Names that cannot be checked come back as state: "invalid" rows, in an immediate answer only. Each checked name and extension uses part of the caller’s domain lookup budget.
Authentication: An API key with the scope read:domains. About keys and scopes
Request
Query parameters
localestringregistryRequirements, for example en.Body
namesarray of stringrequiredExample
curl -X POST "https://cloud.hostup.se/api/v2/domains/availability" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "names": [ "example.se", "example.com" ] }'Responses
200 The check finished at once. data holds one row per name.
{ "data": [ { "name": "example.se", "state": "available", "unknownReason": null, "available": true, "reason": null, "actions": { "canRegister": { "allowed": true, "reason": null }, "canTransfer": { "allowed": false, "reason": "Domain is available for registration, not transfer." } }, "billing": { "amount": 99, "currencyCode": "SEK", "billingCycle": "annually" }, "currencyCode": "SEK", "premium": false, "requiresRegistrarFeeAcceptance": false, "eppRequired": true, "renewalAmount": 169, "supportedRegisterYears": [ 1, 2, 3, 5 ], "supportedTransferYears": [ 1 ], "existingDomainId": null, "existingDomainServiceStatus": null, "registryRequirements": { "registration": [ { "key": "phoneNumber", "label": "Phone number", "required": true, "appliesTo": "register", "registrantType": "any", "allowedCountryCodes": null, "allowedRegistrantTypes": null, "alternativeRequirementKey": null, "acceptedTermsKey": null, "reason": ".se and .nu domains require a registrant phone number before the order can be submitted." }, { "key": "registrationIdentifier", "label": "Personal identity number or organization number", "required": true, "appliesTo": "register", "registrantType": "any", "allowedCountryCodes": null, "allowedRegistrantTypes": null, "alternativeRequirementKey": null, "acceptedTermsKey": null, "reason": ".se and .nu domains require a personal identity number or organization number for the registrant." }, { "key": "acceptedTerms", "label": ".se registration terms", "required": true, "appliesTo": "register", "registrantType": "any", "allowedCountryCodes": null, "allowedRegistrantTypes": null, "alternativeRequirementKey": null, "acceptedTermsKey": "se_registration_terms", "reason": ".se domain registrations require acceptance of the registry registration terms before the order can be submitted." } ], "transfer": [ { "key": "phoneNumber", "label": "Phone number", "required": true, "appliesTo": "transfer", "registrantType": "any", "allowedCountryCodes": null, "allowedRegistrantTypes": null, "alternativeRequirementKey": null, "acceptedTermsKey": null, "reason": ".se and .nu domains require a registrant phone number before the order can be submitted." }, { "key": "registrationIdentifier", "label": "Personal identity number or organization number", "required": true, "appliesTo": "transfer", "registrantType": "any", "allowedCountryCodes": null, "allowedRegistrantTypes": null, "alternativeRequirementKey": null, "acceptedTermsKey": null, "reason": ".se and .nu domains require a personal identity number or organization number for the registrant." }, { "key": "eppCode", "label": "Authorization code", "required": true, "appliesTo": "transfer", "registrantType": "any", "allowedCountryCodes": null, "allowedRegistrantTypes": null, "alternativeRequirementKey": null, "acceptedTermsKey": null, "reason": "Transfers for this domain extension require an authorization code from the current provider." } ], "countryEligibility": { "required": false, "allowedCountryCodes": null, "reason": null } } }, { "name": "example.com", "state": "available", "unknownReason": null, "available": true, "reason": null, "actions": { "canRegister": { "allowed": true, "reason": null }, "canTransfer": { "allowed": false, "reason": "Domain is available for registration, not transfer." } }, "billing": { "amount": 159, "currencyCode": "SEK", "billingCycle": "annually" }, "currencyCode": "SEK", "premium": false, "requiresRegistrarFeeAcceptance": false, "eppRequired": false, "renewalAmount": 189, "supportedRegisterYears": [ 1 ], "supportedTransferYears": [ 1 ], "existingDomainId": null, "existingDomainServiceStatus": null, "registryRequirements": { "registration": [], "transfer": [], "countryEligibility": { "required": false, "allowedCountryCodes": null, "reason": null } } } ]}Response fields
dataarray of objectnamestringstatestringavailable or reason. unknown: the check could not finish. The name is not confirmed taken. Don’t show it as unavailable. already_owned: the name is already registered with Hostup. checking: the check is still running. invalid: the input is not a domain name that can be checked. One of available, unavailable, unknown, already_owned, checking, invalid.unknownReasonstring or nullstate is unknown. null for every other state. One of upstream_timeout, upstream_unavailable.availablebooleanreasonstring or nullactionsobjectcanRegisterobjectallowedbooleanreasonstring or nullnull when it can.canTransferobjectallowedbooleanreasonstring or nullnull when it can.billingobject | nullnull when the check returned no usable registration price.amountnumbercurrencyCodestringbillingCyclestringcurrencyCodestringrenewalAmount and the other prices at the top level. The same as billing.currencyCode when billing is set.premiumbooleanrequiresRegistrarFeeAcceptancebooleaneppRequiredbooleanrenewalAmountnumber or nullcurrencyCode, when known.supportedRegisterYearsarray of integersupportedTransferYearsarray of integerexistingDomainIdstring or nulldom_…) when you already own this name. Otherwise null.existingDomainServiceStatusstring or nullregistryRequirementsobjectregistrationarray of objectkeystringeppCode, phoneNumber, registrationIdentifier, companyRegistrationNumber, birthDate, registrantCountry, registrantType, useDomicile, acceptedTerms, nameservers.labelstringrequiredbooleanappliesTostringregister in registration[], transfer in transfer[]. One of register, transfer, both.registrantTypestringany, private, organisation.allowedCountryCodesarray of any or nullallowedRegistrantTypesarray of any or nullalternativeRequirementKeystring or nullacceptedTermsKeystring or nullreasonstringtransferarray of objectkeystringeppCode, phoneNumber, registrationIdentifier, companyRegistrationNumber, birthDate, registrantCountry, registrantType, useDomicile, acceptedTerms, nameservers.labelstringrequiredbooleanappliesTostringregister in registration[], transfer in transfer[]. One of register, transfer, both.registrantTypestringany, private, organisation.allowedCountryCodesarray of any or nullallowedRegistrantTypesarray of any or nullalternativeRequirementKeystring or nullacceptedTermsKeystring or nullreasonstringcountryEligibilityobject202 The check is queued. Poll operation.pollUrl until status is completed or failed (Jobs).
{ "operation": { "status": "queued", "jobId": "dcheck_01hxa3b4c5d6e7f8g9h0j1k2m3", "pollUrl": "/api/v2/domains/availability/dcheck_01hxa3b4c5d6e7f8g9h0j1k2m3" }}Response fields
operationobjectstatusstringqueued. One of queued.jobIdstringdcheck_...). Poll with this ID. Do not substitute a generic job_... or domain bulk dbj_... ID.pollUrlstringErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | names is missing, empty or has more than 50 entries, no name has a supported extension, or an anonymous caller sent more than one name. |
| 403 | The request has no valid API key with read:domains, no client-area login and no passed human verification. An unknown, expired or revoked key, or a key without read:domains, counts as no key and gets this answer. Automated clients use an API key with read:domains. |
| 429 | The domain lookup budget is used up. It counts checked names (name and extension pairs), not requests. With an API key it is 300 checks per minute and 6,000 per hour. Searches in the client area on the same account use the same budget. The budget starts again on each full minute and each full hour. Refused checks still count. Wait the Retry-After seconds before you check again. See Rate limits. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 503 | Too many checks are queued right now. Wait the Retry-After seconds and try again. |