Copy page

Guides

Register a domain

A registration starts with an exact availability and price check, then one POST /domains request. Domain Chief returns the domain immediately and completes the registry work asynchronously. Store the returned domain ID and use notices and the team event feed to follow what happens next.

Recommended request flow

1. Confirm the selected name and exact price.
2. Create or reuse the required contacts, then prepare the TLD-specific contact roles, DNS settings, intended-use text, and metadata.
3. Make the commercial decision in your application before you submit the registration.
4. Submit the registration once and store the returned domain ID immediately.
5. Present payment or registry-agreement handoffs when the response requires them.
6. Apply the returned domain and notices to your local state.
7. Use the team event feed for later changes and retrieve the domain again when it changes.
8. Offer a correction or retry only when the current notice includes the matching action.

The token needs domainchief:domains:register. Depending on the preparation flow, it may also need the domain availability, TLD, contact, domain read, and event read scopes. The API introduction covers authentication and team selection, and the scope reference lists the available permissions.

Confirm the name and price

Use the domain search and pricing workflow to discover names. Immediately before registration, call Check domain availability for the selected name with expand[]=price:

Code
GET /api/v1/domains/availability/customer-portal.example?expand[]=price HTTP/1.1
Host: domain.chief.app
Authorization: Bearer $TOKEN
X-Chief-Team: $TEAM_ID
Accept: application/json

Continue only when availability is free. Show the exact price and renewal_price, apply your own retail pricing and tax rules, and ask the customer to confirm any change from the earlier search result.

The registration request does not accept a price ceiling or idempotency key. A successful request can charge the team or create an invoice, so perform the final quote and customer confirmation before calling it.

Use Show TLD when you need the selected TLD's current capabilities. In particular, check:

• requires_intended_use before deciding whether to collect an intended-use description.
• supports_whois_privacy before enabling WHOIS privacy.
• the supported contact roles before assigning contact handles.
• DNSSEC support and algorithms before supplying DNSSEC keys.

Capabilities and enum values can grow. Ignore fields you do not use and do not reject a TLD only because a response contains a new value.

Prepare the registration

Contacts and WHOIS privacy

Omit contacts to use the team's default contacts for supported roles. If your application supplies explicit contacts, follow Manage contacts to collect, deduplicate, and store the required handles before registration. The underlying Create a new contact operation returns each handle used here.

Supply only roles the TLD supports. Missing supported roles fall back to the team's defaults, while unsupported roles are ignored.

contacts and is_whois_privacy_enabled are mutually exclusive. Choose one of these approaches:

• Omit both fields to use the team's default WHOIS privacy choice and default contacts.
• Set is_whois_privacy_enabled to true or false to override the team default for this domain.
• Supply contacts when the domain needs explicit role assignments; this disables WHOIS privacy for the request.

Hosted DNS, nameservers, and DNSSEC

Omit DNS fields to use Domain Chief hosted DNS. Set is_using_hosted_dns to false and provide between two and eight nameservers when DNS will be hosted elsewhere:

Code
{
  "is_using_hosted_dns": false,
  "nameservers": [
    {"hostname": "ns1.customer-dns.example"},
    {"hostname": "ns2.customer-dns.example"}
  ]
}

Add glue IPv4 or IPv6 addresses only when the nameserver requires them. Supply dnssec_keys only when the TLD and selected algorithm support DNSSEC. DNSSEC keys describe the child's registry delegation; they do not create DNS records in the hosted zone.

Intended use and metadata

When requires_intended_use is true, collect a concise description of how the registrant will use the domain and send it as intended_use. Do not invent an answer on the customer's behalf.

Use metadata for your own stable references, such as a customer or order ID. Metadata values are strings. It is useful for reconciliation, but it does not replace storing Domain Chief's returned domain ID.

Submit the registration

Call Register or transfer domain once the order or other commercial decision is final:

Code
POST /api/v1/domains HTTP/1.1
Host: domain.chief.app
Authorization: Bearer $TOKEN
X-Chief-Team: $TEAM_ID
Accept: application/json
Content-Type: application/json

{
  "domain": "customer-portal.example",
  "is_using_hosted_dns": false,
  "nameservers": [
    {"hostname": "ns1.customer-dns.example"},
    {"hostname": "ns2.customer-dns.example"}
  ],
  "is_whois_privacy_enabled": false,
  "metadata": {
    "customer_id": "cust_4821",
    "order_id": "ord_9137"
  }
}

A 201 Created response means Domain Chief accepted the request, not necessarily that the registry has activated the domain. In the same transaction as your order state, store at least:

• the returned domain id and canonical domain;
• its current status;
• the complete notices array;
• your own customer and order association.

Clear any short-lived checkout state after this durable association exists. Do not wait for activation before storing the ID.

Reconcile an uncertain response

If the connection ends without a usable response:

1. Call Show domain using the canonical name.
2. If it exists, attach the returned ID to the order and continue from its status and notices.
3. If it returns 404 Not Found, run the exact availability check again.
4. Retry POST /domains only if the name is still free and your application can prove that no accepted request exists.

A 409 Conflict usually means the domain or a competing request already exists. Retrieve the domain before deciding what to show. Do not turn a conflict into an automatic second registration attempt.

Follow the asynchronous result

Use the response's notices immediately. Then follow Sync domains and contacts with your system: establish an event checkpoint before the initial read, poll the team event feed, and retrieve the domain when domain.changed appears. The domain notice guide explains how to render current conditions and actions.

Treat status and notices as separate signals:

• active means the domain is available for normal management.
• requested means processing is still underway; keep the processing notice visible.
• pending_payment requires a customer or billing handoff. Do not submit another registration.
• failed requires the current failure notice to decide whether correction, retry, or support is appropriate.
• Unknown status values are not success. Preserve them, show a neutral pending state, and continue synchronization.

Registry agreements can also block submission. A 400 Bad Request may direct the team to accept an agreement in Domain Chief. There is no public agreement-acceptance endpoint; send an authorized team member through that handoff, then let them explicitly retry the registration.

Retry a failed registration

Offer retry only while the current notice includes domain.registration.retry. After correcting the reported cause, call Retry a failed registration:

Code
POST /api/v1/domains/customer-portal.example/registration/retry HTTP/1.1
Host: domain.chief.app
Authorization: Bearer $TOKEN
X-Chief-Team: $TEAM_ID
Accept: application/json

A 202 Accepted response means the retry started. Replace the displayed domain and notices with that response and resume event-based synchronization. Honor Retry-After after 429 Too Many Requests. On 409 Conflict, retrieve the domain because its state changed before the retry was accepted.

Do not infer retry eligibility from status: failed alone. The notice action is the current authorization and state signal.

Handle request errors

• 400 Bad Request indicates an unsupported TLD option, a missing registry requirement, or a required external handoff such as an agreement.
• 401 Unauthorized and 403 Forbidden require corrected authentication, team selection, or scopes.
• 409 Conflict requires reconciliation with the current domain state.
• 422 Unprocessable Content means the submitted fields failed validation; preserve the customer's form and show field-level corrections.

Do not log contact identity data, authorization headers, or complete request bodies. Keep operational logs to request IDs, your order reference, the canonical domain, response status, and returned Domain Chief resource ID.

API reference

• Check domain availability
• Show TLD
• Create a new contact
• Register or transfer domain
• Show domain
• Retry a failed registration
• List team events
• Domain schema
• DomainNotice schema

Use .example domains to test registrations and failures without buying a public domain.