---
title: "Begin an indexed-domain provider claim"
method: POST
path: "/provider/claims"
---

# Begin an indexed-domain provider claim

`POST /provider/claims`

The returned TXT value must remain published after verification. NHS persists only its SHA-256 token hash, then automatically rechecks domain control; raw DNS answers are not retained.

## Request body

- object
  - `domain` string, required — Domain already present in the NHS index

## Response `201`

Claim, one-time DNS TXT challenge, and ownership-freshness contract

- ProviderClaimChallengeResponse
  - `claim` ProviderClaim, required — Provider ownership state. NHS never returns the persisted challenge-token hash or raw DNS answers.
    - `id` string, uuid, required
    - `site_id` string, uuid, required
    - `domain` string, required
    - `verification_method` 'dns_txt', required
    - `verification_record_name` string, required — TXT record name that must remain published while the claim is verified
    - `status` 'pending' | 'verified' | 'revoked', required
    - `challenge_expires_at` string, date-time, required — Expiry for a pending one-time challenge; it does not authorize removal of a verified TXT record
    - `verified_at` string, date-time, nullable
    - `verification_last_succeeded_at` string, date-time, nullable — Last successful DNS ownership check; paid actions require this to remain within the freshness window
    - `verification_last_attempted_at` string, date-time, nullable
    - `verification_consecutive_failures` integer, required — Consecutive automatic or owner-triggered DNS failures since the last success
    - `verification_next_check_at` string, date-time, nullable — Next scheduled automatic DNS ownership check
    - `revoked_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `dns_challenge` object, required
    - `record_type` 'TXT', required
    - `record_name` string, required
    - `record_value` string, required — Returned once. Keep the full TXT value published after verification; NHS stores only the token hash.
    - `expires_at` string, date-time, required
    - `returned_once` true, required
  - `ownership_freshness` OwnershipFreshness, required — Machine-readable persistent DNS ownership contract and claim-specific safe status; no token, token hash, or raw DNS answer is exposed.
    - `proof_method` 'dns_txt', required
    - `record_must_remain_published` true, required
    - `stored_challenge_material` 'sha256_hash_only', required — NHS persists only the SHA-256 hash of the challenge token
    - `raw_dns_answers_retained` false, required — TXT answers are compared in memory and are not persisted
    - `automatic_reverification` true, required
    - `recheck_interval_seconds` 86400, required — Interval scheduled after a successful check; next_check_at reflects any earlier failure retry
    - `paid_actions_stop_after_consecutive_failures` 3, required — This consecutive failed check revokes the claim and stops paid-action eligibility
    - `paid_actions_stop_when_last_success_age_reaches_seconds` 604800, required — Paid-action eligibility stops at this age even before a revocation update is recorded
    - `last_succeeded_at` string, date-time, nullable, required
    - `next_check_at` string, date-time, nullable, required
    - `consecutive_failures` integer, required
  - `verify_endpoint` string, required

## Other responses

- `401` — Human account session required
- `409` — Domain is already claimed or the account already has a claim

---

[API](https://skmtc.net/nothumansearch/apis/not-human-search-api.md) · [All operations](https://skmtc.net/nothumansearch/apis/not-human-search-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nothumansearch/not-human-search-api/revisions/bdae4e208ce7/schema)