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.

Rules that apply to every domain call

Domain name format

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.

Mixed-alphabet names are rejected

A single label may not combine Latin, Cyrillic, Greek, Arabic, Hebrew, Thai or Lao letters. Registries refuse these as look-alike (homograph) attacks, so we catch them first. The classic case is a Cyrillic а (U+0430) hidden among Latin letters in something like fаcebook.com — visually identical, a different domain entirely.

Chinese, Japanese and Korean scripts count as one family and may be combined with each other, but not with Latin. Digits and hyphens are neutral. Turkish characters (ç ö ü ğ ş ı İ) are Latin, so they never cause this. Sending the punycode form does not bypass the check — we decode it first.

Error: Dna.DomainService:Domain:10058, message “Domain name mixes multiple scripts”. Note that this code is also used for a completely different, far more serious condition — see Error codes.

The period field

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.

The nameServers field

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"]

Extra registry fields: tldAttributes

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.

Where the keys and values come from

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.

Build the form from the catalogue, not from a hard-coded list

Render the extra fields dynamically from attributes. New extension requirements then work without a code change, you never send a key the registry does not recognise, and the permitted values for dropdowns always match what the registry accepts.

Worked example: .tr domains

Turkish domains are the most involved case. In the test environment you can register them with the following attributes:

{
  "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": "Ataturk Caddesi No 12 Kat 3",
      "city": "Istanbul",
      "state": "Istanbul",
      "postalCode": "34100",
      "country": "TR",
      "phoneCountryCode": "90",
      "phone": "5321234567"
    }
  ],
  "tldAttributes": {
    "TRABISDOMAINCATEGORY": "Corporate",
    "TRABISTAXNUMBER": "11111111111",
    "TRABISTAXOFFICE": "Yok"
  }
}

These values are for the test environment

11111111111 and "Yok" are accepted by the test registry so you can exercise the flow end to end. In production you must send the customer’s real tax number and real tax office — the registry verifies them against official records.

The attributes depend on each other

.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 — checked as a tax number (or an 11-digit identity number) TRABISTAXOFFICE — checked as a tax office
Owner	TRABISCITIZENID — checked as an 11-digit 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.

The contact and the attributes must agree — this one has consequences

The extra attributes are validated together with the contact you send, not in isolation. In particular, the registrant’s country changes how they are checked: Turkish tax and identity numbers are only verified when the registrant’s country is TR. Send a different country and that check is skipped — your value is accepted here and passed straight to the registry.

The registry then does its own verification, after registration. If the details do not match official records, the domain can be suspended or deleted, and a deleted domain is not something we can recover for you.

So before you register:

• Make sure country, the address and the tax or identity number describe the same real entity.
• Use the customer’s actual registered address, not your own and not a placeholder.
• Treat a successful registration as “accepted”, not “verified” — the registry’s own check comes later.

What a bad attribute value gives you

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 not exactly 11 digits.
Validation:IdentityNumber:Format	It is not 11 digits, or it starts with 0.
Validation:IdentityNumber:RepeatedDigits	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	The number is well-formed but fails its check-digit calculation. Almost always a typo.
Dna.TaxNoValidatorError	The tax number is not a valid 10-digit tax number and not a valid 11-digit identity number.
Dna.RequiredValidatiorError	An attribute the registry treats as mandatory was left empty. (The key is spelled this way in the response — match it literally.)

Validate before you buy

Attribute validation happens during registration, which is also when your balance is checked. A rejected attribute does not charge you, but it does mean a round trip and a failed order on your record. Validate tax and identity numbers in your own form first — the rules above are enough to catch almost every bad value before it reaches us.

Trustee service: useTrusteeContact

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.

What changes when you use a trustee

• Your contacts array and tldAttributes are both replaced by the trustee’s. Anything you send in them is discarded.
• The domain costs more — a second line item appears on the order.
• Contact verification does not apply: the contacts are the trustee’s, not your customer’s.
• PUT /api/v1/domains/contacts/update is afterwards refused with Dna.DomainService:Domain:10037.
• GET /api/v1/domains/info returns an empty contacts array.

Check isSupportTrustee and isTrusteeRequired in the catalogue. If isTrusteeRequired is true and you omit the flag, registration fails with Dna.DomainService:Trustee:10006.

How paid operations work

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.

Three codes that mean “do not retry”

Code	What happened
Dna.DomainService:Domain:10058	The domain was registered at the registry, but we could not write our own record.
Dna.DomainService:Domain:10059	The domain was renewed at the registry, but we could not record it.
Dna.DomainService:Domain:10060	The transfer was started at the registry, but we could not record it.

In all three cases the operation succeeded. A recovery record has been created and our team will reconcile it. Retrying creates a duplicate registration or a double charge. Open a support ticket with the domain name and your correlation ID instead.

The message text tells you which of the two meanings of 10058 you have: a registry message means do-not-retry; “mixes multiple scripts” means your input was rejected and nothing happened.