> ## 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/v2/concepts/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 `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.

## Claim or change the domain

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

A direct administrator of the organization can claim, and so can Apostra staff
signed in to Apostra's own account. Staff working inside your organization
through a support session 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.

## Related

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

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


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