Create, read and update contacts

POST /api/v1/contacts

Creates a contact and returns its handle code. Nothing is sent to any registry yet — that happens when you use the handle to register or update a domain.

Request

A single contact object. All fields follow the contact field reference. There is no contactType here — the role is decided when you use the handle.

{
  "contact": {
    "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"
  }
}

Response — 200

{
  "handle": "D-174829301847",
  "isSuccess": true,
  "operationMessage": "Operation completed successfully"
}

What to do with it

Store handle against your customer record. This is the only time it is returned for a newly created contact, and it is what you send to POST /api/v1/domains/register. Losing it means creating a duplicate contact.

Errors

Code	Meaning and fix
(validation)	HTTP 400 with validationErrors. Read members to see which field. Typical: a required field missing, a name that became empty after invalid characters were removed, or a + in phoneCountryCode.
Dna.DomainService:Contact:10011	Invalid e-mail address.
Dna.DomainService:Contact:10013	Phone country code contains something other than digits.
Dna.DomainService:Contact:10014	Phone number is not usable after normalisation.

GET /api/v1/contacts/{handleCode}

Reads a contact in your account, together with any verification process currently open on it.

Request

GET /api/v1/contacts/D-174829301847

Response — 200

{
  "contact": {
    "handle": "D-174829301847",
    "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"
  },
  "verificationObjects": [
    {
      "fieldType": "Email",
      "fieldValue": "ahmet@apiname.com",
      "ownerName": "Ahmet Yilmaz",
      "operationStatus": "VerificationPending",
      "isUserVerified": false,
      "tokenExpireDate": "2026-11-14T10:22:31",
      "resendDate": "2026-10-30T10:23:31",
      "attemptNumber": 1,
      "resendRetryCount": 100
    }
  ]
}

What to do with it

Check verificationObjects first. An empty array means nothing is outstanding. If an entry has isUserVerified: false, the tokenExpireDate is the date the domain will be suspended — show it to your customer and chase them before it arrives.

Errors

Code	Meaning and fix
Dna.DomainService:Contact:Verification:10006	Handle not found in your account. Check for a typo, and that the handle is yours.

PUT /api/v1/contacts/{handleCode}

Updates a contact. This is not a local edit — the change is pushed to the registry of every domain using this handle, and the response reports what happened to each one.

This is a replace, not a patch

Send the complete contact. Any field you leave out is not preserved. Read the contact first, change what you need, send it all back.

Request

PUT /api/v1/contacts/D-174829301847

{
  "contact": {
    "firstName": "Ahmet",
    "lastName": "Yilmaz",
    "companyName": "Apiname Ltd",
    "eMail": "ahmet@apiname.com",
    "address": "Bagdat Caddesi No 45 Daire 7",
    "city": "Istanbul",
    "state": "Istanbul",
    "postalCode": "34728",
    "country": "TR",
    "phoneCountryCode": "90",
    "phone": "5329876543"
  }
}

Response — 200

{
  "handle": "D-174829301847",
  "contactUpdateSuccess": true,
  "stats": {
    "totalDomainCount": 3,
    "successCount": 2,
    "pendingDocumentCount": 0,
    "failedCount": 0,
    "splitCount": 1
  },
  "affectedDomains": [
    {
      "domainName": "apiname.com",
      "status": "Success",
      "newHandle": null,
      "reason": "Updated",
      "message": "Handle update completed"
    },
    {
      "domainName": "apiname.net",
      "status": "Success",
      "newHandle": null,
      "reason": "RddsPending",
      "message": "Handle update completed, RDDS verification started"
    },
    {
      "domainName": "apiname.com.tr",
      "status": "Success",
      "newHandle": "D-R-1748293018",
      "reason": "SplitNotSubjectToRdds",
      "message": "Moved to a new handle, not subject to RDDS verification"
    }
  ]
}

Reading the response

Field	Meaning
contactUpdateSuccess	Whether the contact record itself was saved.
stats.totalDomainCount	How many domains use this handle.
stats.successCount	Updated at the registry.
stats.pendingDocumentCount	The registry wants documents before accepting the change.
stats.failedCount	The registry rejected the change.
stats.splitCount	Domains moved onto a new handle instead of being updated.
affectedDomains[].reason	Updated · RddsPending (verification started) · SplitForDocument · SplitNotSubjectToRdds · Failed
affectedDomains[].newHandle	Set when that domain was moved to a new handle. null otherwise.

Always read newHandle

When domains using one handle cannot all take the same change, we move the ones that cannot onto a newly created handle rather than leaving your records inconsistent. That domain is no longer reachable through the handle you just updated.

Loop over affectedDomains and, for every entry where newHandle is not null, store the new handle against that domain in your database. Skipping this is the most common integration bug in this endpoint.

Does the handle code change?

No. The handle string stays the same — only its contents change. Your stored handle keeps working for future registrations. The two exceptions:

• A domain was split off (newHandle is set). For that domain the handle changed; your original handle is still valid for everything else.
• An identity change is awaiting verification. The contact is updated but the registry change is held until the owner confirms. A domain you register with the handle meanwhile uses the new details and starts its own verification.

Errors

Code	Meaning and fix
Dna.DomainService:Domain:10038	Handle not found.
Dna.DomainService:Contact:10012	Invalid country — not a recognised ISO2 code.
Dna.DomainService:Contact:10020	The handle is linked to at least one domain that is not yours. Nothing was changed.
Dna.DomainService:Contact:Verification:10008	An ownership-change verification is already open on this contact. Wait for it to finish, or have the owner reject it, before changing identity again.
Dna.DomainService:Contact:Verification:10010	You are changing the name, surname or company, and the contact’s e-mail is not verified. Verify the e-mail first — see the sequence below.
Dna.DomainService:Contact:10026	The handle is used by several domains in a way we cannot split safely. Open a support ticket.
Dna.DomainService:Epp:10001	The registry rejected the change. Per-domain detail is in affectedDomains.