> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Your organization's domain

> Read and claim the domain your organization operates as

An organization claims the domain it operates as. Its accounts use that domain:
a buyer account as its operator domain, with its own operating-unit code, and a
seller account as its brand domain. See [Which domain is which](https://docs.apostra.com/v3/domains.md)
for how this differs from the domains used for sign-in.

These routes need a signed-in person: the web app, or an assistant connected
with your Apostra sign-in. API keys and other machine credentials are refused.

## Read the organization's domains

`GET /api/v2/accounts/{customerId}/organization-domains`

`customerId` is the organization. An administrator of the organization can read
it, and so can Apostra staff supporting the organization.

```json theme={null}
{
  "data": {
    "domains": [
      {
        "domain": "acme.com",
        "state": "verified",
        "proofMethod": "staff_review",
        "provedAt": "2026-10-24T21:09:53.598Z",
        "accountIds": ["804", "805"]
      }
    ]
  },
  "error": null
}
```

| Field | Type | Notes |
| - | - | - |
| `data.domains` | array | The organization's claimed domains. Empty when it claims none |
| `data.domains[].domain` | string | The claimed domain |
| `data.domains[].state` | string | `claimed` (saved, not proved), `verifying` (a DNS check is open or a staff review was requested) or `verified` |
| `data.domains[].proofMethod` | string \| null | `dns_txt`, `staff_review` or `aao_sign_in` once verified, otherwise `null` |
| `data.domains[].provedAt` | string \| null | When it was proved, otherwise `null` |
| `data.domains[].accountIds` | array | The organization's accounts that use the domain |

### Errors

* `401 UNAUTHORIZED`: no signed-in person.
* `403 ACCESS_DENIED`: the caller is neither an administrator of the organization nor Apostra staff supporting it, or used an API key.
* `404 NOT_FOUND`: the account is not an active organization.

## See the domains in the Domains page

In the web app, open **Settings → Organization → Domains** while you're in your
organization's account, or select a domain in the Organization's Accounts list.
From one of the organization's accounts, selecting a domain switches you to the
organization first: domains are managed in the organization's own account.

In an assistant connected to your organization's account, ask to open the
Domains page, or call `open_domains_page`.

The page shows the same domains as the read above: for each one, whether it is
proved and how, when it was proved, the accounts that use it, and whether it is
locked.

A domain is locked when accounts using it have advertisers. Its claim cannot
change, because changing it would change those accounts' identity at every
seller. The page names the accounts that hold the lock.

An administrator of the organization can open the page, from any of its
accounts, and so can Apostra staff supporting the organization.

An administrator also claims, changes and proves the domain on the page. These
follow the same rules as the routes below:

* **Claim or change.** The page sends the domain you last saw with each change,
  so a change someone else made meanwhile is refused instead of overwritten.
  A locked domain offers no change.
* **Prove with a DNS record.** The page shows the TXT record to publish. Check
  it once it's published; if another organization also claims the domain, the
  check files a staff review instead.
* **Ask Apostra to review.** Apostra staff review the claim and follow up by
  email, so this needs a signed-in person with an email address.

Apostra staff supporting the organization see the page without these actions.

## Claim or change the domain

`PUT /api/v2/accounts/{customerId}/organization-domains/claim`

A direct administrator of the organization can claim, from any of its accounts
(the web app moves you into the organization to open its settings), and so can
Apostra staff signed in to Apostra's own account. Staff working inside your
organization through a support session, or switched into it, cannot claim for
it. An organization claims one
domain. Claiming a different domain changes the claim: the accounts
using it move with it and keep their operating-unit codes, and the new domain
starts unproved. Only one organization can verify a domain: a domain another
organization has verified cannot be claimed.

| Field | In | Type | Required | Notes |
| - | - | - | - | - |
| `operatorDomain` | body | string | Yes | The domain to claim, such as `acme.com` |
| `expectedDomain` | body | string \| null | Yes | The claimed domain as you last read it, or `null` when the organization claimed none |

```json theme={null}
{
  "data": {
    "claim": {
      "domain": "acme.com",
      "previousDomain": null,
      "changed": true,
      "accountsUsingClaim": [804, 805]
    }
  },
  "error": null
}
```

| Field | Type | Notes |
| - | - | - |
| `data.claim.domain` | string | The claimed domain |
| `data.claim.previousDomain` | string \| null | The domain claimed before, or `null` |
| `data.claim.changed` | boolean | `false` when the organization already claimed this domain |
| `data.claim.accountsUsingClaim` | array | The accounts that moved with the claim |

Read the organization's domains again to see the claim's state.

### Errors

* `400 VALIDATION_ERROR`: a missing field, or a value that is not a domain.
* `401 UNAUTHORIZED`: no signed-in person.
* `403 ACCESS_DENIED`: the caller is not a direct administrator of the organization or Apostra staff in Apostra's own account, used a support session, or used an API key.
* `404 NOT_FOUND`: the account is not an active organization.
* `409 CONFLICT`, with a `reason`:
  * `organisation_domain_verified_elsewhere`: another organization has already verified the domain. Ask Apostra for a staff review if your organization operates as it.
  * `organisation_claim_changed`: the claim changed since you read it. Read it again and retry.
  * `organisation_claim_in_use`: accounts using the current claim have advertisers. Changing it would change their identity at every seller.
  * `organisation_claim_unit_taken`: an account's operating-unit code is already used under the new domain.

## Prove the domain

An organization proves its claimed domain the same two ways an account proves
its registered domain: a DNS TXT record, or a review by Apostra staff. Start the
DNS check on the organization itself (see
[Verify with a DNS record](https://docs.apostra.com/v2/buyer/account/tasks/verify-operator-domain.md#verify-with-a-dns-record));
for an organization that claims a domain, the record proves the claimed domain.

Proving the claim also makes it the organization's approved registered domain.
On an organization the two are one domain, so one proof covers what your
accounts operate as at sellers, [domain auto-join](https://docs.apostra.com/v2/buyer/account/tasks/update-membership.md)
to the organization, and eligibility for single sign-on. Your accounts keep
their own auto-join settings, and each takes its registered domain from the
organization's verified domains (see below).

If another organization also claims the domain, or has it as its registered
domain, a passing DNS check does not verify it. The check answers with
`reviewRequested: true` and keeps the TXT record in place, and Apostra staff
decide which organization owns the domain. Until then the domain reads as
`verifying`. Filing the review needs a signed-in person with an email address,
so Apostra can follow up.

## Pick an account's auto-join domain

Every domain is held at the organization. An account does not type a domain of
its own: its registered domain, the one that decides email auto-join, is one of
the organization's **verified** domains, or none.

* **A child buyer or agents account** picks from the organization's verified
  domains, or clears the domain. In the web app this is **Settings → Account configuration → Auto-join domain**
  in the child account. The picked domain takes the organization's proof, so it
  needs no DNS record or review of its own.
* **A domain the account already holds** that the organization has not verified
  stays as it is, with the approval it has today, until you clear it or replace
  it with one of the organization's domains. It cannot be edited to another
  typed domain.
* **The organization's own account** has no such setting: its domain is the claim
  above.
* **A seller account** keeps its own brand domain, typed and verified as before,
  until the organization's claims take it over in a later step.
* **A standalone account** types and verifies its own domain, as before.
* **An account that converts into a child** of a new organization keeps the
  domain it has, as a held domain.

In the **Add account** dialog a Buyer account takes the same picker (default
none); a Seller account keeps its typed brand domain. When someone signs up to a
child buyer or agents account that has no domain, the account takes their email
domain only if the organization has verified it.

To use a new domain, claim and prove it on the organization first, then pick it
on the account. The same rule applies to
[updating an account's domain](https://docs.apostra.com/v2/buyer/account/tasks/update-customer-domain.md)
and to [creating an account](https://docs.apostra.com/v2/buyer/account/tasks/create-child-account) with
a domain: for a buyer or agents account, a domain the organization has not
verified is refused with a `400 VALIDATION_ERROR` that points to the Domains
page. Seller accounts and Apostra staff are not restricted.

## Related

> [card] [Verify operator domain](https://docs.apostra.com/v2/buyer/account/tasks/verify-operator-domain.md)
>
> Prove control of the domain

> [card] [Which domain is which](https://docs.apostra.com/v3/domains.md)
>
> Sign-in, operator and brand domains


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.