Skip to content

Get availability check results

GET /api/v2/domains/availability/{jobId}

Returns the progress and results of an availability check started with POST /api/v2/domains/availability. Use the dcheck_... ID from operation.jobId. operation.pollUrl already points here. A generic job_... or domain bulk dbj_... ID returns 400. While status is processing, data can already hold partial results for names that have finished. Poll until status is completed or failed. A completed check returns data in the same shape as the immediate POST answer. A completed check leaves out names whose extension Hostup does not sell, extensions past the eighth for the same name and names whose check failed. Compare data[].name with the names you sent. Check a missing name again on its own. Prices are in SEK. currencyCode and billing.currencyCode are always SEK. Finished checks are kept for a limited time, and a busy period shortens it. Read the results as soon as status is completed. A check that is no longer kept returns 404 job_not_found. A check started by an account (API key or client-area login) can only be read by that account. Others get 404 job_not_found, and so does a request whose API key is unknown, revoked or lacks read:domains. existingDomainId is filled only for authenticated callers.

Authentication: An API key with the scope read:domains. About keys and scopes

Request

Path parameters

jobIdstringrequired
The availability check ID from operation.jobId. It starts with dcheck_.

Query parameters

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

Example

GET /api/v2/domains/availability/{jobId}
curl "https://cloud.hostup.se/api/v2/domains/availability/dcheck_01hxa3b4c5d6e7f8g9h0j1k2m3" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The check’s status, with results when there are any.

{
"status": "completed",
"data": [
{
"name": "example.se",
"state": "unavailable",
"unknownReason": null,
"available": false,
"reason": "Domain already registered.",
"actions": {
"canRegister": {
"allowed": false,
"reason": "Domain already registered."
},
"canTransfer": {
"allowed": true,
"reason": null
}
},
"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
}
}
}
]
}
Response fields
statusstring
processing: poll again. completed: data holds the results. failed: no name could be checked and reason says so. Start a new check. One of processing, completed, failed.
progressnumber
How far the check is, from 0 to 100. Present while status is processing.
dataarray of object
The results. Always present when status is completed. While status is processing, the names that are done. Left out until the first one is.
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
reasonstring
Present when status is failed.

Errors

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

400The ID is a generic job_... or domain bulk dbj_... ID, not an availability check ID.
404No check has this ID. A check that belongs to another account answers the same.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.