Skip to content

Domains

Everything you can do to a domain name: check availability, register, renew, transfer, and manage it afterwards. This is the largest section — the shared rules come first, then the endpoints grouped by task.

We accept Unicode and punycode, normalise to lowercase, and validate against the public suffix list so that apiname.co.uk and apiname.com.tr are understood as whole domains rather than subdomains.

A name is rejected when:

  • it contains no dot, or has an empty label (apiname..com);
  • any label starts or ends with a hyphen (-apiname.com, apiname-.com);
  • it is longer than 63 characters;
  • it mixes alphabets within one label — see below.

Registration, renewal and transfer term, in years.

  • Valid range is 1–10, but the real constraint is per TLD. The catalogue’s registrationPeriods and renewalPeriods arrays list the exact terms you may send. A registration outside registrationPeriods gives Dna.DomainService:Domain:10023; a renewal outside renewalPeriods gives Dna.DomainService:Domain:10002.
  • On renewal, 0 is treated as 1.
  • Premium domains accept period: 1 only. Registry premium fees are quoted a year at a time. Anything higher is rejected with Dna.DomainService:Domain:10071.

Required when registering. At least one entry; the per-TLD minimum and maximum are enforced (usually 2–13). To use our own DNS — which is what makes the DNS records API work — send:

["tr.apiname.com", "eu.apiname.com"]

Some extensions demand data beyond the standard contact set — a tax number for .com.tr, a citizenship declaration for .eu, a nexus category for .us. You supply these as a flat key/value object alongside the rest of the registration request.

Do not guess them and do not hard-code them. Every valid key is published in the attributes array of the TLD catalogue:

GET /api/v1/products/tlds?filterText=com.tr

See the TLD catalogue for the full response, or the extension’s own page under TLDs. Each entry in attributes gives you everything you need to build the form:

Catalogue field Use it for
key The key to send in tldAttributes.
description The label to show.
type Text, DropdownList, RadioButton, Checkbox, CheckboxWithContract, FileUpload or Label — tells you which input to render. Label entries are informational only.
options The exact permitted values, each as { "value": "..." }. Send one of these verbatim; anything else is rejected.
isRequired Whether registration fails without it.

Turkish domains are the most involved case. Everything in this example and below applies to every .tr extension — .tr itself, .com.tr, .net.tr, .org.tr, .av.tr, .gen.tr and the others listed under TLDs. They all use the same four keys.

You can try .tr registrations in the test environment as often as you like. Send POST /api/v1/domains/register-with-contacts with a registrant outside Turkey and placeholder numbers. For a company:

{
"domainName": "apiname.com.tr",
"period": 1,
"nameServers": ["tr.apiname.com", "eu.apiname.com"],
"contacts": [
{
"contactType": "Registrant",
"firstName": "Ahmet",
"lastName": "Yilmaz",
"companyName": "Apiname Ltd",
"eMail": "ahmet@apiname.com",
"address": "12 King Street",
"city": "London",
"state": "London",
"postalCode": "EC1A 1AA",
"country": "GB",
"phoneCountryCode": "44",
"phone": "2079460123"
}
],
"tldAttributes": {
"TRABISDOMAINCATEGORY": "Corporate",
"TRABISTAXNUMBER": "11111111111",
"TRABISTAXOFFICE": "Yok"
},
"useTrusteeContact": false
}

For an individual, send Owner and an identity number instead of the two tax fields:

"tldAttributes": {
"TRABISDOMAINCATEGORY": "Owner",
"TRABISCITIZENID": "11111111111"
}

.tr is a good illustration of something that applies to several extensions: one attribute decides which others are required and how they are checked.

TRABISDOMAINCATEGORY What is then required and validated
Corporate TRABISTAXNUMBER — must not be empty; for a registrant in TR, checked as a 10-digit tax number or an 11-digit identity number
TRABISTAXOFFICE — must not be empty, whatever the country
Owner TRABISCITIZENID — must be exactly 11 characters, whatever the country; for a registrant in TR, also checked as a national identity number

Send the wrong category and you will either be asked for a field you were not expecting, or the field you did send will go unchecked and reach the registry unverified.

A registrant outside Turkey can register a .tr domain through the API. Set the registrant’s country to their own ISO2 code, not TR, give their real address, and send:

Registrant TRABISDOMAINCATEGORY Also send
Foreign company Corporate companyName on the contact.
TRABISTAXNUMBER: the company’s tax or registration number in its own country. Any non-empty value is accepted.
TRABISTAXOFFICE: the authority that issued that number. Must not be empty.
Foreign individual Owner TRABISCITIZENID: an identity number of exactly 11 characters. A foreign national who holds a Turkish foreign identity number (11 digits, starting with 99) sends that.
Code Meaning and fix
Dna.DomainService:TldAttribute:10001 You sent a key this extension does not define. details lists the offending keys. Check them against attributes[].key in the catalogue — a common cause is reusing keys from a different extension.
Dna.DomainService:TldAttribute:10002 A required attribute is missing. details names it in readable form. Remember that which attributes are required can depend on the value of another one.
Dna.DomainService:TldAttribute:10003 A value failed validation. The message names the field; data.ValidationError carries the specific rule that failed — see the table below.
Dna.DomainService:TldAttribute:10004 This extension does not support internationalised (IDN) names.
Dna.DomainService:TldAttribute:10005 Value longer than the attribute allows. details gives the limit.

When 10003 is raised, data.ValidationError tells you exactly which rule rejected the value:

data.ValidationError What was wrong
Validation:IdentityNumber:Length The identity number is empty or not exactly 11 characters. Checked for every registrant country, including registrants outside Turkey — see Foreign registrants.
Validation:IdentityNumber:Format Registrant in TR only: it is not 11 digits, or it starts with 0.
Validation:IdentityNumber:RepeatedDigits Registrant in TR only: the same digit repeats 6 or more times in a row — rejected as an obviously fake number even when the checksum passes.
Validation:IdentityNumber:Checksum Registrant in TR only: the number is well-formed but fails its check-digit calculation. Almost always a typo.
Dna.TaxNoValidatorError The tax number is empty, or — for a registrant in TR — not a valid 10-digit tax number and not a valid 11-digit identity number.
Dna.TaxAdministrationValidatorError TRABISTAXOFFICE is empty. It is required for Corporate, whatever the country.
Dna.RequiredValidatiorError An attribute the registry treats as mandatory was left empty. (The key is spelled this way in the response — match it literally.)

Some country extensions require a local presence. Setting useTrusteeContact: true on registration buys our trustee service and uses the trustee’s details as the domain’s contacts.

Register, renew, transfer and restore all debit your balance. The sequence is: check your account is in good standing → look up your price → check your balance → send the command to the registry → record it → charge you.

Two consequences worth designing for:

  • A price seal is taken when you search. For premium domains the registry quote is re-checked at purchase; if it moved, the purchase is refused with Dna.DomainService:Domain:10072 and nothing is charged. Search again to get the current price.
  • If the registry succeeds but we cannot record it, you get a never-retry error. See the box below — this is the most important operational rule in the API.