---
title: "Record an NHS-observed handoff and reveal the provider action URL"
method: POST
path: "/action-tickets/handoff"
---

# Record an NHS-observed handoff and reveal the provider action URL

`POST /action-tickets/handoff`

Presents the raw ticket bearer and the separate exact nhs-provider-handoff-consent-v1 principal attestation only in a bounded JSON body, never in the NHS URL or query string; every response is private, no-store. NHS atomically records one append-only privacy-safe nhs-action-handoff-v1 receipt bound to the exact ticket, offer version, commercial-terms hash, and handoff-consent version before returning the attributed provider action URL. The principal may separately and optionally authorize the exact DNS-verified provider to resolve only the bounded controlled-intent bundle under nhs-provider-controlled-intent-disclosure-consent-v1; declining that disclosure does not block this handoff or free direct provider access. The receipt contains no query, agent or principal identity, contact data, network address, referrer, or user agent. This handoff and the optional resolver charge neither party; only the configured authenticated provider-reported downstream outcome can create the disclosed provider charge. Exact wording is at https://nothumansearch.ai/privacy#handoff-consent-v1 and https://nothumansearch.ai/privacy#controlled-intent-disclosure-consent-v1.

## Request body

- ActionTicketHandoffRequest — Exact ticket bearer and separate handoff-time principal attestation are accepted only in JSON, not in the NHS URL, query string, referrer, or cookie. The controlled-intent disclosure pair is optional; false or omission requires no version, while true requires the exact v1 version. Declining it does not block handoff.
  - `ticket_id` string, uuid, required
  - `attribution_token` string, required
  - `principal_handoff_consent` true, required — Caller attests the exact published handoff-time principal authorization
  - `handoff_consent_version` 'nhs-provider-handoff-consent-v1', required
  - `principal_controlled_intent_disclosure_consent` boolean — Optional separate authorization for the exact DNS-verified provider to resolve the bounded controlled-intent bundle after this observed handoff
  - `controlled_intent_disclosure_consent_version` 'nhs-provider-controlled-intent-disclosure-consent-v1' — Required only when principal_controlled_intent_disclosure_consent is true; otherwise omit

## Response `200`

Exact replay of the existing durable handoff receipt and provider URL; neither party charged

- ActionTicketHandoffResponse
  - `ticket` PublicActionTicket, required — Controlled consent-attested ticket snapshot. Provider action URL, token hash, token nonce, signing-key metadata, and internal evidence references are excluded.
    - `id` string, uuid, required
    - `provider_claim_id` string, uuid, required — Opaque provider claim identifier; not a provider identity or contact field
    - `provider_offer_id` string, uuid, required
    - `search_receipt_id` string, uuid — Removed when controlled intent is redacted
    - `offer_version` integer, required
    - `offer_name` string, required
    - `offer_summary` string, required
    - `action_type` 'lead' | 'demo' | 'trial' | 'signup' | 'purchase' | 'quote' | 'application' | 'booking', required
    - `disclosure` 'Provider-funded action', required
    - `charge_event` 'accepted' | 'activated' | 'converted', required
    - `bounty_cents` integer, required
    - `currency` 'usd', required
    - `billing_mode` 'terms', required
    - `commercial_terms_contract_version` 'nhs-provider-commercial-terms-v1', required
    - `commercial_terms_sha256` string, required
    - `principal_price_mode` 'free' | 'fixed' | 'quote' | 'provider_pricing', required
    - `principal_price_cents` integer
    - `principal_currency` 'usd', required
    - `demand_topic` 'payments' | 'commerce' | 'jobs' | 'data' | 'search' | 'weather' | 'maps' | 'email' | 'messaging' | 'image' | 'video' | 'audio' | 'documents' | 'security' | 'finance' | 'health' | 'education' | 'news' | 'analytics' | 'automation' | 'productivity' | 'identity' | 'storage' | 'ai-tools' | 'developer-tools' | 'other' | 'redacted', required
    - `region_code` string
    - `budget_band` 'unspecified' | 'under_100' | '100_499' | '500_1999' | '2000_plus', required
    - `urgency` 'unspecified' | 'now' | '7_days' | '30_days' | 'researching', required
    - `requirement_flags` string[], required
    - `principal_consent` true, required
    - `consent_version` 'nhs-principal-consent-v1', required
    - `status` 'created' | 'redirected' | 'accepted' | 'activated' | 'converted' | 'rejected' | 'duplicate' | 'invalid', required
    - `expires_at` string, date-time, required
    - `intent_redacted_at` string, date-time
    - `authorization_revoked_at` string, date-time
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `handoff_receipt` ProviderActionHandoffReceipt, required — Durable append-only privacy-safe NHS observation. Internal claim ID and presented-token hash are not returned.
    - `id` string, uuid, required
    - `action_ticket_id` string, uuid, required
    - `provider_offer_id` string, uuid, required
    - `offer_version` integer, required
    - `commercial_terms_contract_version` 'nhs-provider-commercial-terms-v1', required
    - `commercial_terms_sha256` string, required
    - `principal_handoff_consent` true, required
    - `handoff_consent_version` 'nhs-provider-handoff-consent-v1', required
    - `principal_controlled_intent_disclosure_consent` boolean, required — False means no provider resolution authorization; the handoff remains valid
    - `controlled_intent_disclosure_consent_version` 'nhs-provider-controlled-intent-disclosure-consent-v1'
    - `event_contract_version` 'nhs-action-handoff-v1', required
    - `observed_at` string, date-time, required
    - `created_at` string, date-time, required
  - `action_url` string, uri, required — Attributed HTTPS provider URL returned only after the durable receipt commits
  - `observed_handoff` true, required
  - `idempotent_replay` boolean, required
  - `principal_charged` false, required
  - `provider_charged` false, required
  - `organic_rank_affected` false, required
  - `direct_provider_access_is_free` true, required

## Other responses

- `201` — New durable observed-handoff receipt and attributed provider URL; neither party charged
- `400` — Invalid JSON
- `404` — Ticket or exact bearer not found
- `409` — Verified commercial evidence unavailable
- `410` — Ticket attribution expired; neither party charged
- `429` — Temporary handoff safety limit exceeded

---

[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)