Skip to content

Knowledgebase

Update domain contact roles with the current v2 API

domain-nexus, development

Use PUT /v2/domains/{domainId}/contacts to request changes to the contact assignments of an owned domain. Read the current contacts first and submit only the intended, authorised changes in the registrar workflow's accepted format.

01 Prepare the contact change

Your credential needs domains:contacts. Resolve the current domain identifier, read its contacts and check the TLD's current requirements. Confirm the owner has approved any registrant identity change and understands any verification or transfer-lock consequence.

The current connector uses role objects with fields such as first_name, last_name, company_name, email, phone_e164, address1, city, state, postal_code and country_code. Use the roles and mandatory values accepted for that domain.

API request example
PUT /v2/domains/DOMAIN_ID/contacts
Idempotency-Key: contact-change-local-1042
Content-Type: application/json

{
  "contacts": {
    "registrant": {
      "first_name": "Alex",
      "last_name": "Example",
      "email": "[email protected]",
      "phone_e164": "+12025550123",
      "address1": "123 Example Street",
      "city": "Example City",
      "state": "CA",
      "postal_code": "90001",
      "country_code": "US"
    }
  }
}

This illustrates the payload shape, not a substitute for the customer's real contact details or the registry's complete requirements. Do not copy sample identities into a live registration.

02 Follow the result

  1. Submit the reviewed JSON using the authentication helper and a stored idempotency key.
  2. Retain the operation reference and inspect its final status.
  3. Complete any registrar verification requested through the approved process.
  4. Read the assigned contacts again and compare the accepted values with the intended change.

Will updating one domain contact automatically update every domain?

Updating a reusable contact profile alone does not necessarily change a registered domain. Conversely, changing the registrant for one domain should not be treated as permission to replace every customer's contact profile.

For multiple domains, use a reviewed portfolio workflow and account for different registry requirements. Avoid a bulk replacement that erases technical or billing roles the owner intended to retain.

03 Handle failures

Read validation errors for the specific field or role. For a timeout or pending state, inspect the original operation before retrying. Keep personal data out of support logs; provide the operation reference and redacted field names unless an approved support channel requires more detail.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support