Skip to content

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

localestring
Language hint for the labels in registryRequirements, for example en.

Body

namesarray of stringrequired
Full domain names to check, 1 to 50.

Example

POST /api/v2/domains/availability
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.

Response 200
{
"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 object
namestring
The domain name, in lowercase.
statestring
The result of the check. Read it instead of available 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 null
Why the check could not finish: it timed out or the lookup service was unavailable. Present only when state is unknown. null for every other state. One of upstream_timeout, upstream_unavailable.
availableboolean
True when the domain can be registered now.
reasonstring or null
Why the domain cannot be registered, ready to show.
actionsobject
canRegisterobject
allowedboolean
reasonstring or null
Why this action cannot be done, ready to show. null when it can.
canTransferobject
allowedboolean
reasonstring or null
Why this action cannot be done, ready to show. null when it can.
billingobject | null
Billing summary for a registration. null when the check returned no usable registration price.
amountnumber
currencyCodestring
billingCyclestring
currencyCodestring
ISO 4217 currency of renewalAmount and the other prices at the top level. The same as billing.currencyCode when billing is set.
premiumboolean
True when the registry sells the name as premium.
requiresRegistrarFeeAcceptanceboolean
True when the order must accept an extra registrar fee.
eppRequiredboolean
True when a transfer of this domain needs an authorization code.
renewalAmountnumber or null
Price of a one-year renewal in currencyCode, when known.
supportedRegisterYearsarray of integer
The registration periods you can order, in years. Only use years present in this array.
supportedTransferYearsarray of integer
The transfer periods you can order, in years. A free transfer still lists its year.
existingDomainIdstring or null
The domain ID (dom_…) when you already own this name. Otherwise null.
existingDomainServiceStatusstring or null
The service status of your existing domain, when you own it.
registryRequirementsobject
What a registration or transfer of this TLD needs.
registrationarray of object
keystring
One of eppCode, phoneNumber, registrationIdentifier, companyRegistrationNumber, birthDate, registrantCountry, registrantType, useDomicile, acceptedTerms, nameservers.
labelstring
requiredboolean
appliesTostring
register in registration[], transfer in transfer[]. One of register, transfer, both.
registrantTypestring
One of any, private, organisation.
allowedCountryCodesarray of any or null
allowedRegistrantTypesarray of any or null
alternativeRequirementKeystring or null
acceptedTermsKeystring or null
reasonstring
transferarray of object
keystring
One of eppCode, phoneNumber, registrationIdentifier, companyRegistrationNumber, birthDate, registrantCountry, registrantType, useDomicile, acceptedTerms, nameservers.
labelstring
requiredboolean
appliesTostring
register in registration[], transfer in transfer[]. One of register, transfer, both.
registrantTypestring
One of any, private, organisation.
allowedCountryCodesarray of any or null
allowedRegistrantTypesarray of any or null
alternativeRequirementKeystring or null
acceptedTermsKeystring or null
reasonstring
countryEligibilityobject

202 The check is queued. Poll operation.pollUrl until status is completed or failed (Jobs).

Response 202
{
"operation": {
"status": "queued",
"jobId": "dcheck_01hxa3b4c5d6e7f8g9h0j1k2m3",
"pollUrl": "/api/v2/domains/availability/dcheck_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
}
Response fields
operationobject
statusstring
Always queued. One of queued.
jobIdstring
The availability check ID (dcheck_...). Poll with this ID. Do not substitute a generic job_... or domain bulk dbj_... ID.
pollUrlstring
The URL to poll for the results.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400names is missing, empty or has more than 50 entries, no name has a supported extension, or an anonymous caller sent more than one name.
403The 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.
429The 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.
500Internal error. Retry later or contact support if the issue persists.
503Too many checks are queued right now. Wait the Retry-After seconds and try again.