# Create register URL: https://docs.hanzo.ai/docs/openapi/domain/post-domain-register > Buys a domain for your org and answers the ownership record together with the quote it was bought at. `POST /v1/domain/register` > [Domain →](https://docs.hanzo.ai/docs/openapi/domain) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | ----------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/domain/register` | | **Method** | `POST` | | **Operation** | `post_domain_register` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Buys a domain for your org and answers the ownership record together with the quote it was bought at. The order of operations is the product guarantee: quote, refuse anything unpurchasable or unpriced, AUTHORIZE the org's prepaid balance, provision the authoritative zone in Hanzo DNS, register at the registrar already pointing at Hanzo's nameservers, and only then CAPTURE the charge and record ownership. A registrar failure therefore leaves the balance untouched — the org is never billed for a domain it did not get. It requires a validated principal; that principal's org owns the domain and is the ledger the charge lands on. Re-buying a name the org already holds is 409, not a second purchase. Refusals are distinct on purpose: 402 when the prepaid balance cannot cover the quoted price, 409 when the name is not available, 503 when the deployment has no registrar credentials, and the registrar's own message with its own 4xx — or 502 for its 5xx — when it rejects the purchase. Zone provisioning is best-effort: if the zone service is down the domain is still registered against Hanzo's nameservers and the zone reconciles afterwards, rather than the purchase failing. ## Request 55 fields, body `application/json` (required). | Field | In | Type | Required | Description | | --------------------------------- | ---- | ----------------- | -------- | ------------------------------------------ | | `contacts` | body | domain.Contacts | — | | | `contacts.admin` | body | domain.Registrant | — | | | `contacts.admin.address1` | body | string | — | street address | | `contacts.admin.address2` | body | string | — | second address line | | `contacts.admin.city` | body | string | — | city or locality | | `contacts.admin.companyName` | body | string | — | the organisation the contact acts for | | `contacts.admin.country` | body | string | — | ISO-3166 alpha-2, e.g. "US" | | `contacts.admin.email` | body | string | — | where WHOIS correspondence is sent | | `contacts.admin.fax` | body | string | — | fax number, in the same form as phone | | `contacts.admin.firstName` | body | string | — | the contact's given name | | `contacts.admin.lastName` | body | string | — | the contact's family name | | `contacts.admin.phone` | body | string | — | +NN.NNNNNNN | | `contacts.admin.state` | body | string | — | state, province or region | | `contacts.admin.zip` | body | string | — | postal code | | `contacts.billing` | body | domain.Registrant | — | | | `contacts.billing.address1` | body | string | — | street address | | `contacts.billing.address2` | body | string | — | second address line | | `contacts.billing.city` | body | string | — | city or locality | | `contacts.billing.companyName` | body | string | — | the organisation the contact acts for | | `contacts.billing.country` | body | string | — | ISO-3166 alpha-2, e.g. "US" | | `contacts.billing.email` | body | string | — | where WHOIS correspondence is sent | | `contacts.billing.fax` | body | string | — | fax number, in the same form as phone | | `contacts.billing.firstName` | body | string | — | the contact's given name | | `contacts.billing.lastName` | body | string | — | the contact's family name | | `contacts.billing.phone` | body | string | — | +NN.NNNNNNN | | `contacts.billing.state` | body | string | — | state, province or region | | `contacts.billing.zip` | body | string | — | postal code | | `contacts.registrant` | body | domain.Registrant | — | | | `contacts.registrant.address1` | body | string | — | street address | | `contacts.registrant.address2` | body | string | — | second address line | | `contacts.registrant.city` | body | string | — | city or locality | | `contacts.registrant.companyName` | body | string | — | the organisation the contact acts for | | `contacts.registrant.country` | body | string | — | ISO-3166 alpha-2, e.g. "US" | | `contacts.registrant.email` | body | string | — | where WHOIS correspondence is sent | | `contacts.registrant.fax` | body | string | — | fax number, in the same form as phone | | `contacts.registrant.firstName` | body | string | — | the contact's given name | | `contacts.registrant.lastName` | body | string | — | the contact's family name | | `contacts.registrant.phone` | body | string | — | +NN.NNNNNNN | | `contacts.registrant.state` | body | string | — | state, province or region | | `contacts.registrant.zip` | body | string | — | postal code | | `contacts.tech` | body | domain.Registrant | — | | | `contacts.tech.address1` | body | string | — | street address | | `contacts.tech.address2` | body | string | — | second address line | | `contacts.tech.city` | body | string | — | city or locality | | `contacts.tech.companyName` | body | string | — | the organisation the contact acts for | | `contacts.tech.country` | body | string | — | ISO-3166 alpha-2, e.g. "US" | | `contacts.tech.email` | body | string | — | where WHOIS correspondence is sent | | `contacts.tech.fax` | body | string | — | fax number, in the same form as phone | | `contacts.tech.firstName` | body | string | — | the contact's given name | | `contacts.tech.lastName` | body | string | — | the contact's family name | | `contacts.tech.phone` | body | string | — | +NN.NNNNNNN | | `contacts.tech.state` | body | string | — | state, province or region | | `contacts.tech.zip` | body | string | — | postal code | | `domain` | body | string | yes | Domain is the name to buy. | | `years` | body | integer (int64) | — | Years is the term to buy, defaulting to 1. | ## Response | Status | Body | Meaning | | --------- | --------------------- | ------- | | `200` | domain.RegisterResult | ok | | `default` | problem-details | refused | `200` body — 17 fields. | Field | In | Type | Always | Description | | ------------------------- | ---- | --------------- | ------ | ------------------------------------------------------ | | `quote` | body | domain.Offer | — | | | `quote.available` | body | boolean | — | whether it can be bought right now | | `quote.currency` | body | string | — | the currency both prices are in | | `quote.domain` | body | string | — | the name this quote prices | | `quote.premium` | body | boolean | — | whether the registry prices it above the standard rate | | `quote.priceCents` | body | integer (int64) | — | sell (first-term registration) | | `quote.renewalPriceCents` | body | integer (int64) | — | sell (renewal) | | `quote.tld` | body | string | — | the top-level domain the name sits under | | `record` | body | domain.Holding | — | | | `record.costCents` | body | integer (int64) | — | wholesale cost | | `record.domain` | body | string | — | the name owned | | `record.expiresAt` | body | string | — | when the registration lapses, RFC3339 | | `record.nameservers` | body | string\[] | — | the authoritative nameservers the name points at | | `record.order` | body | integer (int64) | — | registrar order id | | `record.org` | body | string | — | the org that owns the domain | | `record.priceCents` | body | integer (int64) | — | what the customer paid (sell) | | `record.registeredAt` | body | integer (int64) | — | unix seconds | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo domain register --domain ``` **SDK** **.ts** ```ts import { Configuration, DomainApi } from 'hanzoai'; const api = new DomainApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.postDomainRegister({ domain: "" }); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import DomainApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = DomainApi(client).post_domain_register(domain="") ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.DomainAPI.PostDomainRegister(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, domain_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = domain_api::post_domain_register(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.DomainApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new DomainApi(client).postDomainRegister(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/domain/register \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "" }' ``` **MCP** MCP reaches **domain** through the `domain` tool, which names its 7 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "describe", "arguments": { "op": "get_domain_availability" } } }' ``` --- [Domain API](https://docs.hanzo.ai/docs/openapi/domain) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)