# Contacts

> The four contact roles, handle codes, and the field-by-field rules for contact data, including phone number format.

A contact is the person or organisation behind a domain name. Every domain has four contact roles, and registries publish some of this data. Contacts are addressed by a **handle code** — a short identifier you can reuse across many domains.

## The four roles

| Value | Name | Who this is |
| --- | --- | --- |
| 1 | `Registrant` | **The legal owner of the domain.** The most important role — ownership disputes and transfer approvals go to this contact. |
| 0 | `Admin` | The administrative contact, authorised to make changes. |
| 3 | `Tech` | The technical contact, for DNS and operational matters. |
| 2 | `Billing` | The billing contact. |

:::note[You can use one contact for all four roles]
Most resellers do. The registry requires four roles to be filled, not four different people. Where you send contact details inline, we fill the remaining roles for you — see [Registering with contact details](https://www.domainnameapi.com/docs/domains/register/#registering-with-contact-details).
:::

## Handle codes

A handle code looks like this:

```text
D-174829301847
```

- Always starts with `D-`.
- You will also see a role-scoped form such as `D-R-1748293018`. We create these automatically when one domain's contact has to diverge from the others. Treat any handle as an opaque string — do not parse it.
- Maximum 20 characters.
- **A handle belongs to your account.** Another reseller's handle is invisible to you.
- A handle can back all four roles on one domain, and can be shared across many domains.

:::caution[Sharing a handle across domains has consequences]
Updating a shared handle updates the contact on **every** domain using it, and each of those domains goes to its registry. That is usually what you want — one address change, everywhere. But if you need one domain to differ, give it its own handle instead of editing the shared one.
:::

## Contact field reference

These rules apply everywhere you send a contact — creating one, updating one, or registering a domain with contact details inline. Read this once; the endpoints below will not repeat it.

| Field | Required | Max | Rules and what we do to your value |
| --- | --- | --- | --- |
| `firstName` | required | 80 | Letters, spaces, `.` and `,` only. **Anything else is removed silently**, and what remains must be at least 2 characters. `"John99"` becomes `"John"`; `"99"` becomes empty and is rejected. |
| `lastName` | required | 80 | Same rule as `firstName`. |
| `companyName` | optional | 256 | Letters, digits, spaces and `.,'&()/-` survive; other characters are removed. **If you leave it empty we set it to "firstName lastName".** For an individual registrant, simply omit it. |
| `eMail` | required | 256 | Must be a deliverable address — see the warning below. |
| `address` | required | 256 | Letters, digits, spaces and `.,:/#()-` survive. Line breaks, tabs and runs of spaces collapse to one space. Minimum 4 characters. Send the street address on one line. |
| `city` | required | 80 | Letters, digits and spaces only. Minimum 2. |
| `state` | required | 80 | Same rule as `city`. **If your country has no states, repeat the city.** It cannot be empty. |
| `postalCode` | required | 15 | Letters, digits and spaces only. Minimum 2. |
| `country` | required | 2 | **ISO 3166-1 alpha-2, uppercase.** `"TR"`, `"US"`, `"GB"`, `"DE"`. Not the country name, not a three-letter code. See the warning below. |
| `phoneCountryCode` | required | 3 | **Digits only. No `+` sign.** `"90"` is correct; `"+90"` is rejected. |
| `phone` | required | 16 | Minimum 5 digits. We normalise it — see below. |
| `fax, faxCountryCode` | optional | 15 / 3 | Digits only. If either is invalid we clear both rather than failing your request. Omit them entirely unless you have a real fax number. |
| `discloseFlag` | optional | — | **Omit it.** Leaving it out means "do not touch WHOIS disclosure". Only send `true`/`false` if you are deliberately setting disclosure at creation time. It is ignored when updating a contact — use domain privacy instead. |
| `contactType` | varies | — | Required in some places, absent in others. Each endpoint states it. |

:::caution[Always validate `country` before you send it]
The `country` field must be a valid ISO 3166-1 alpha-2 code. A value we do not recognise is **not guaranteed to be stored as you submitted it**, and an incorrect country reaches the registry's public records. Validate against the ISO2 list in your own code — do not rely on the API to reject a bad value here. Common mistakes: `"Turkey"`, `"TUR"`, `"turkey"`, `"UK"` (the correct code for the United Kingdom is `GB`).
:::

:::danger[The e-mail address must be real and monitored]
This is the single most consequential field in the whole API. For most domain extensions, the registrant's e-mail address has to be **verified by clicking a link**. If nobody clicks it within **15 days**, the domain is **suspended and stops resolving**. Never use a placeholder, a no-reply address, or an address the customer does not read. See [Contact verification](https://www.domainnameapi.com/docs/contacts/verification/).
:::

### Phone number format

We accept most formats and normalise them. The steps, in order: strip everything that is not a digit; remove the country code if the number repeats it; remove a single leading zero.

All four of these arrive as country code `90`, number `5321234567`:

```json
"+90 (532) 123 45 67"
"0532 123 45 67"
"905321234567"
"5321234567"
```

The registry receives `+90.5321234567`. The one thing you must get right is keeping the `+` out of `phoneCountryCode`.