Skip to Content
Uptimeify Docs
Status pages

Verify Status Page Domain

Verifies DNS TXT records for a custom status page domain. Organization-wide: admin only; customer-bound: by the page's ownership class.

POST /api/status-pages/domains/verify

Access: organization-wide callers need the role admin (an organization-wide editor or readonly gets 403 forbidden). Customer-bound users (also with the role readonly) and customer-bound API tokens follow the ownership class of the page the domain is bound to: allowed on self_service pages, on managed pages only with the customer's canEditManaged exception, otherwise 403 with data.code: managed_by_organization. A domain bound to no status page does not exist for a customer-bound caller: 404 (domainNotFound).

Request Body

FieldTypeRequiredDescription
domainIdnumberYesThe domain ID to verify

Example (cURL)

curl -X POST "$BASE_URL/api/status-pages/domains/verify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "domainId": 42 }'

Response (success)

{
  "verified": true,
  "status": "verified",
  "domain": {
    "id": 42,
    "hostname": "status.deinkunde.com",
    "status": "verified",
    "role": "status_page",
    "verificationToken": "abc123-def456-ghi789",
    "verifiedAt": "2026-05-01T12:00:00.000Z",
    "lastVerificationError": null,
    "lastVerificationErrorAt": null,
    "createdAt": "2026-05-01T11:00:00.000Z",
    "updatedAt": "2026-05-01T12:00:00.000Z"
  }
}

Common errors

  • 401 Unauthorized when not authenticated
  • 403 Forbidden when you are an organization-wide caller without the role admin
  • 403 Forbidden (managed_by_organization) when you are customer-bound (user, also with the role readonly, or token) and the page is managed without the customer's canEditManaged exception
  • 404 Not Found (domainNotFound) when you are customer-bound and the domain is bound to no status page
  • 404 Not found when the domain does not exist
  • 400 domainVerificationFailed when the TXT record was not found. The error data says what we saw, so you can fix the record without guessing:
{
  "statusCode": 400,
  "statusMessage": "TXT verification failed (token not found)",
  "data": {
    "code": "domainVerificationFailed",
    "recordName": "_verify-status.status.example.com",
    "expected": "a1b2c3d4e5f6",
    "lookup": "records",
    "observed": ["old-token-from-another-tool"],
    "nameservers": { "zone": "example.com", "hosts": ["ns1.dns-provider.example", "ns2.dns-provider.example"] },
    "authoritative": { "nameserver": "ns1.dns-provider.example", "lookup": "records", "observed": ["a1b2c3d4e5f6"] },
    "propagation": "propagating"
  }
}

lookup is records (TXT values found, none matches; they are in observed, at most 10), noRecords (the name exists but has no TXT record), nxdomain (the name does not exist), timeout or error (resolver failure, retry later). nameservers is the zone the hostname is delegated in and its authoritative nameservers (null if that could not be determined). authoritative is what one of those nameservers answered when asked directly for recordName, bypassing every cache (null if none could be asked; only public addresses are queried). propagation reads both answers: propagating (your nameserver has the token, our resolver does not see it yet, retry after the TTL), not_published (not even your nameserver has it), unknown (no nameserver could be asked).

The failure is also stored on the domain: every domain response carries it as lastVerificationError with lastVerificationErrorAt until the next successful verification clears both.

  • 409 Conflict (domainAlreadyClaimed) when another organization has already verified or activated this hostname. The owner is not disclosed.

On this page