---
title: "Claim a new domain"
method: POST
path: "/domains"
tags: ["Domains"]
---

# Claim a new domain

`POST /domains`

Creates an unverified domain claim and returns the exact
DNS records to publish in `dns_records`. Publish those
records before calling the verify endpoint. To give users
an importable DNS file, call `downloadDomainZoneFile` or run
`primitive domains zone-file --id <domain-id>`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `domain` string, required — The domain name to claim (e.g. "example.com")
  - `confirmed` boolean — Set to true to confirm replacing an existing mailbox provider after an mx_conflict response.
  - `outbound` boolean — Deprecated and ignored. Outbound DNS is provisioned for every new domain claim.

## Response `201`

Domain claim created

- object
  - `success` true, required
  - `data` object, required
    - `id` string, uuid, required
    - `org_id` string, uuid, required
    - `domain` string, required
    - `verified` false, required
    - `verification_token` string, required — Add this value as a TXT record to verify ownership
    - `dns_records` object[] — Exact DNS records to publish for a pending domain claim or verification attempt.
      - `type` 'MX' | 'TXT', required — DNS record type.
      - `name` string, required — DNS-provider host/name value relative to the managed root zone.
      - `fqdn` string, required — Fully-qualified DNS record name.
      - `value` string, required — Exact value to publish.
      - `priority` integer — MX priority. Present only for MX records.
      - `ttl` integer — Suggested TTL in seconds when the API can provide one.
      - `required` true, required
      - `purpose` 'inbound_mx' | 'ownership_verification' | 'spf' | 'dkim' | 'dmarc' | 'tls_reporting', required
      - `status` 'pending' | 'found' | 'missing' | 'incorrect', required
      - `message` string — Short explanation of why this record is needed.
    - `created_at` string, date-time, required

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `409` — The request conflicts with the current state of the resource

---

[API](https://skmtc.net/primitive/apis/primitive-api.md) · [All operations](https://skmtc.net/primitive/apis/primitive-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/primitive/primitive-api/versions/c2299d28022c/schema)