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
namestringrequiredThe full domain name, including the extension.
localestringLanguage hint for the labels in
registryRequirements, for example en.Example
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.
{ "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
namestringThe domain name, in lowercase.
statestringThe 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 nullWhy 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.availablebooleanTrue when the domain can be registered now.
reasonstring or nullWhy the domain cannot be registered, ready to show.
actionsobjectcanRegisterobjectallowedbooleanreasonstring or nullWhy this action cannot be done, ready to show.
null when it can.canTransferobjectallowedbooleanreasonstring or nullWhy this action cannot be done, ready to show.
null when it can.billingobject | nullBilling summary for a registration.
null when the check returned no usable registration price.amountnumbercurrencyCodestringbillingCyclestringcurrencyCodestringISO 4217 currency of
renewalAmount and the other prices at the top level. The same as billing.currencyCode when billing is set.premiumbooleanTrue when the registry sells the name as premium.
requiresRegistrarFeeAcceptancebooleanTrue when the order must accept an extra registrar fee.
eppRequiredbooleanTrue when a transfer of this domain needs an authorization code.
renewalAmountnumber or nullPrice of a one-year renewal in
currencyCode, when known.supportedRegisterYearsarray of integerThe registration periods you can order, in years. Only use years present in this array.
supportedTransferYearsarray of integerThe transfer periods you can order, in years. A free transfer still lists its year.
existingDomainIdstring or nullThe domain ID (
dom_…) when you already own this name. Otherwise null.existingDomainServiceStatusstring or nullThe service status of your existing domain, when you own it.
registryRequirementsobjectWhat a registration or transfer of this TLD needs.
registrationarray of objectkeystringOne of
eppCode, phoneNumber, registrationIdentifier, companyRegistrationNumber, birthDate, registrantCountry, registrantType, useDomicile, acceptedTerms, nameservers.labelstringrequiredbooleanappliesTostringregister in registration[], transfer in transfer[]. One of register, transfer, both.registrantTypestringOne of
any, private, organisation.allowedCountryCodesarray of any or nullallowedRegistrantTypesarray of any or nullalternativeRequirementKeystring or nullacceptedTermsKeystring or nullreasonstringtransferarray of objectkeystringOne of
eppCode, phoneNumber, registrationIdentifier, companyRegistrationNumber, birthDate, registrantCountry, registrantType, useDomicile, acceptedTerms, nameservers.labelstringrequiredbooleanappliesTostringregister in registration[], transfer in transfer[]. One of register, transfer, both.registrantTypestringOne of
any, private, organisation.allowedCountryCodesarray of any or nullallowedRegistrantTypesarray of any or nullalternativeRequirementKeystring or nullacceptedTermsKeystring or nullreasonstringcountryEligibilityobjectErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | The 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. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 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. |
| 502 | Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. 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. |