---
title: API
description: Programmatic domain verification
showNextPage: true
originalPath: .tmp-workos-clone/packages/docs/content/domain-verification/api.mdx
---

Instead of leveraging the Admin Portal, the Domain Verification API can be used to verify domains programmatically.

Integrating with the API goes as follows:

1. Create an organization domain for an organization
2. Share the token and setup instructions with the organization owner (IT admin)
3. Wait for the verification to complete

## Create a new organization domain

All domains belong to an [organization](/reference/organization). In order to create and verify a domain, an organization must first be [created](/reference/organization/create).

<CodeBlock title="Create an organization domain">
  <CodeBlockTab title="Request" file="create-organization-domain" />
  <CodeBlockTab title="Response" file="create-organization-domain-response" />
</CodeBlock>

The `verification_token` returned can then be set as the value of a TXT record that WorkOS will periodically check until the record is found. The TXT record for the above response example would be:

- Name: `domain-to-verify.com`
- Value: `verification_token=3CVZxo4HgvSiYRKlV4RdOWwWl`

## Get a domain

Fetch an existing domain and it’s current verification status. This endpoint can be polled once verification has been initiated to determine if verification has been successful.

<CodeBlock title="Fetch an organization domain">
  <CodeBlockTab title="Request" file="get-organization-domain" />
  <CodeBlockTab title="Response" file="get-organization-domain-response" />
</CodeBlock>

Possible `state` values:

- `pending`: domain verification has been initiated and not yet completed
- `verified`: domain has been verified
- `failed`: domain was not able to be verified

Possible `verification_strategy` values:

- `dns`: domain is verified with the DNS flow
- `manual`: domain is verified by a person or a system, without running the DNS flow

## Initiate verification for existing domain

If a domain has not successfully verified within thirty days and moves to the `failed` state, verification can be restarted manually.

<CodeBlock title="Verify an existing organization domain">
  <CodeBlockTab title="Request" file="verify-existing-organization-domain" />
  <CodeBlockTab
    title="Response"
    file="verify-existing-organization-domain-response"
  />
</CodeBlock>