Manage contacts
Domain Chief stores registrant and other domain contacts as team-scoped resources. Create or reuse a contact for the person or organization it represents, store the returned handle, and pass that handle when registering, transferring, or updating a domain. Do not send the full contact details with every domain request.
Recommended request flow
- Collect the current contact details.
- Create or reuse the contact and store the returned handle with the corresponding record in your system.
- Read the TLD's supported contact roles.
- Assign explicit contact handles during registration or transfer.
- Update a shared contact carefully, or create a replacement when an immutable identity field changes.
- Apply contact events to your local copy.
- Hand registrant verification to the registrant when a domain notice requires it.
Reading contacts needs domainchief:contacts:read; creating, updating, or deleting them needs domainchief:contacts:write. Reading TLD capabilities and affected domains needs domainchief:tlds:read and domainchief:domains:read. Assigning a contact during registration or transfer needs domainchief:domains:register, while changing an existing domain needs domainchief:domains:write. Event-driven synchronization also needs domainchief:events:read. The scope reference lists all Domain Chief permissions.
Before creating contacts, the Domain Chief team must have a valid, verified default contact. An authorized team member can complete that prerequisite through Domain Chief's team setup.
Model contacts in your integration
Keep authorization in your application
Treat handle as the stable Domain Chief identifier and store it beside your own contact or account ID. A handle belongs to the selected Domain Chief team. It is not proof that the signed-in user may manage the corresponding record in your application, so enforce that authorization yourself.
Contact creation deduplicates identical details by default. This means two local records can receive the same Domain Chief handle when they represent the same person or organization. Model the association accordingly instead of assuming one handle belongs to one local record.
You can attach your own string identifiers as metadata. Use them for reconciliation, not authorization. If one Domain Chief contact can map to several local records, keep those associations in your database rather than overwriting one metadata value.
parent_handle can group contacts under another contact in Domain Chief. It is organizational only and does not affect registration, transfer, authorization, or domain ownership. Do not use it as an account or authorization boundary.
Separate team defaults from explicit contacts
is_default is team-wide. Mark a contact as the default only when it should be the fallback for every domain managed by the team. When different domains need different registrants, send the intended handle explicitly for the owner role.
When a registration or transfer omits a supported role, Domain Chief uses the team's default contact for that role. Decide which contact should fill each administrative, technical, and billing role. Never let the fallback select an unintended registrant.
Create or reuse a contact
Collect registry-compatible details
Collect current details from the person or organization the contact represents over an authenticated connection. Create a new contact requires a first and last name, street and house number, postal code, city, two-letter country code, email address, and international phone number.
Keep the street name and house number in separate fields. Send the country as an uppercase ISO 3166-1 alpha-2 code. Domain Chief accepts a full state or province name or its abbreviation and returns the stored abbreviation.
Set company_name when the registrant is a company. The first and last name are still required for its representative. Some registries also require a company registration number, trading name, website, VAT number, or fields in extension_data.
Fields such as passport numbers, national identity codes, and birth dates are sensitive. Collect TLD-specific data only when the selected registry requires it. Do not put it in logs, analytics, support transcripts, URLs, or contact metadata. See the contact creation contract for the current field formats and the Contact schema for returned fields.
Send the create request
Omit allow_duplicate for the normal flow:
Code
Domain Chief returns 201 Created for a new contact and 200 OK when it finds an identical team contact. Treat both as success and store data.handle from the response:
Code
Use allow_duplicate: true only when your separation or retention rules require distinct Domain Chief resources for identical details. It disables the built-in reuse behavior and can leave several handles representing the same person or organization.
Treat the returned contact as authoritative. A 200 OK response can reuse a handle that another local record already references. Confirm that its mutable and TLD-specific fields fit the new domain before assigning it. Update the shared contact only when the change should affect every domain that uses it; otherwise create a separate contact with allow_duplicate: true.
Assign contacts to domains
Read the supported contact roles
Call Show TLD and inspect handle_types before building the domain's contacts object:
Code
The response can include owner, admin, tech, billing, and reseller. Build your form and request from the returned values. Ignore contact-role values your integration does not yet recognize, and do not reject the TLD merely because Domain Chief adds a role.
The owner contact is the registrant. Assign the person or organization that should legally hold the domain. Choose the other supported roles according to the integration's operating model and the registry's rules.
Assign contacts during registration or transfer
Pass handles in the contacts object used by Register or transfer domain:
Code
Send only roles listed in the TLD's handle_types. During registration or transfer, an omitted supported role falls back to the team's default contact. An unsupported role is ignored.
contacts and is_whois_privacy_enabled cannot appear in the same request. Supplying explicit contacts disables WHOIS privacy for that request. Handle this conflict in your interface rather than silently dropping the selected privacy setting.
Continue with Register a domain or Transfer a domain into Domain Chief for the rest of each request.
Change contacts on an existing domain
Call Update a domain to replace one or more roles:
Code
Only the supplied roles change. Send an empty contacts object to reset all roles to team defaults. Supplying contacts disables WHOIS privacy and cannot be combined with is_whois_privacy_enabled.
The returned domain may contain a processing or verification notice because registry-facing changes finish asynchronously. Apply the returned notices immediately, then use the team event feed to retrieve the domain after domain.changed.
Update or retire a contact
Update a contact safely
A contact handle can be assigned to several domains. Before calling Update a contact, find every local record and domain that references it and confirm that the change applies to all of them.
The update request is partial. Omitted fields keep their current values:
Code
Changing the email of a contact already in use can require the registrant to verify the new address. A TLD can also reject updated details that no longer meet its requirements. Preserve the form and show the field or TLD errors from 422 Unprocessable Content.
The update operation does not accept first_name, last_name, company_name, or address_country_code. When one of those values changes, create a replacement contact, update every affected domain role to its new handle, and follow the returned domain notices. Retire the old contact only after no domain uses it.
Delete an unused contact
A contact cannot be deleted while a domain uses it, while it is the team's default, or when it is the team's only remaining contact. Reassign those dependencies first and confirm the current domains no longer reference the handle.
Call Delete a contact:
Code
Success returns 204 No Content.
Handle registrant verification
Registrant verification is reported on the affected domain, not as a status on the contact resource. The current domain.contact_verification.required notice tells you whether the registrant must open a verification URL or whether your integration can request another email. Follow Hand off contact verification for the complete notice rules.
Use an email address the registrant can access. Show a verification link only while the current notice contains domain.contact_verification.open and a contact_verification_url. Open that URL in the registrant's browser. Do not fetch, log, cache, or modify it because it may contain a time-limited token.
Call Resend contact verification only while the current notice contains domain.contact_verification.resend:
Code
Replace the displayed domain and notices with the 200 OK response. A 400 Bad Request means the domain is not currently eligible for another email. On 429 Too Many Requests, wait for the number of seconds in Retry-After instead of retrying on your own schedule.
After the registrant completes verification, wait for domain.changed, retrieve the domain, and replace the old notice snapshot. Do not assume the external page succeeded merely because the browser returned to your application.
Keep contacts synchronized
Use Sync domains and contacts with your system when your application keeps a local contact copy. Apply contact.created and contact.changed by retrieving the current handle with Show contact or List specific contacts. Remove the local resource after contact.deleted.
Match contacts by handle, not by names or email addresses. Those details can change and are not stable identifiers for your own records.
Handle request errors
401 Unauthorizedand403 Forbiddenrequire corrected authentication, team selection, scopes, team setup, or contact permissions.404 Not Foundmeans the handle or domain is absent from the selected team.422 Unprocessable Contentmeans the contact fields or a linked TLD requirement failed validation. Preserve the submitted input and show the returned field errors.
Contact requests and responses contain personal data. Keep operational logs to request IDs, your own non-sensitive reference, the response status, and the returned handle. Apply your retention and access-control rules to any local copy of the contact.