Skip to content

Check domain availability

GET /api/v2/domains/availability

Checks whether one domain name can be registered or transferred and what it costs. Use it before you order a domain. actions.canRegister and actions.canTransfer say which order is possible. registryRequirements lists the fields the order must include for the TLD. Order only periods listed in supportedRegisterYears or supportedTransferYears. state: "unknown" means the check could not finish. The name is not confirmed taken. To check several names at once, use POST /api/v2/domains/availability. Each check 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

namestringrequired
The full domain name, including the extension.
localestring
Language hint for the labels in registryRequirements, for example en.

Example

GET /api/v2/domains/availability
curl "https://cloud.hostup.se/api/v2/domains/availability?name=example.se" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The availability, price and order requirements of the name.

Response 200
{
"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
}
}
}
Response fields
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

Errors

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

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403The request has no API key with read:domains, no client-area login and no passed human verification. Automated clients use an API key with read:domains. A key without that scope is treated as anonymous.
404Not found. The resource does not exist or is not owned by the caller.
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.
502Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists.
503Too many checks are queued right now. Wait the Retry-After seconds and try again.