ClaimListing — instructions for agents

One account. Proof per business.

ClaimListing is a shared claim-verification service for directories. A directory publishes a business listing before the operator arrives; the real operator proves that listing is theirs and takes control of it. The proof — who verified what, when, through which on-file contact, with what evidence — lives in the ClaimListing ledger, not with any agent. Claim across directories that trust this ledger.

Proof is per business. Verifying one business never verifies another. Each business's proof goes to the contact already on file for THAT business (the Doorstep rule) — never to an address supplied by a claimant or an agent.

The mandate rule

An agent never acts merely because it referred the owner. To act for a principal you need a scoped authorization (a mandate): principal × agent × businesses × permitted actions × expiry, revocable by the principal at any time. Every action you take is recorded against your agent identity and the mandate it rode on. Revocation freezes dependent claims immediately.

How a claim works

  1. Initiate. POST /api/v1/claims with your tenant API key (scope claims.initiate), the tenant's listing reference, and the principal you act for. Include an Idempotency-Key header — retries with the same key return the same claim, never a duplicate. The response is deliberately generic: {"status":"received","reference":"…"}. It does not confirm whether the business exists.
  2. Issue the challenge. POST /api/v1/claims/{id}/challenge. ClaimListing sends the approval link to the contact on file for the business. You never see the link or the destination.
  3. The human approval moment. The owner opens the link, sees the listing, the action, and your agent identity named plainly, and makes one deliberate click (a POST — opening the link alone never approves anything). That click is the human signing. A clean claim approves itself at that moment; anything suspicious routes to a human review queue instead — it is never silently denied.
  4. Poll status. GET /api/v1/claims/{id}/status (scope claims.status) returns {"status","tier","reason","federation"}. Status is how you learn the outcome; there is no webhook in v1a.

Minimal example flow

POST /api/v1/claims
Authorization: Bearer clk_…
Idempotency-Key: 7f3c…-uuid
Content-Type: application/json

{"listingRef":"estate-sale-co-42","principalId":"…",
 "claimMethod":"api","sourceChannel":"agent_initiated",
 "agentIdentity":{"platform":"your-platform","workloadId":"…"},
 "authorizationMode":"standing_delegation","authorizationId":"…"}

→ 202 {"status":"received","reference":"<claim-id>"}

POST /api/v1/claims/<claim-id>/challenge   → 200 {"outcome":"issued", …}
# the owner approves from their own inbox — you do nothing here
GET  /api/v1/claims/<claim-id>/status      → 200 {"status":"verified_keyed", …}

Error and reason codes

Errors are deterministic: AUTH_MISSING, AUTH_INVALID, AUTH_REVOKED, FORBIDDEN_SCOPE, FORBIDDEN_TENANT, SESSION_INVALID, NOT_OWNER, NOT_FOUND, VALIDATION, INVALID_FIELD (with the offending input named in the field property — an enum field such as sourceChannel or claimMethod outside its vocabulary is a 400, never a 500), CHALLENGE_INVALID (with the challenge failure as reason: TOKEN_MISMATCH, EXPIRED, ALREADY_CONSUMED, BINDING_MISMATCH), NOT_ACTIONABLE, NOT_ISSUABLE, NO_CONTACT, QUEUE_NOT_FOUND, QUEUE_ALREADY_CLOSED. Claim statuses come from the claim state machine (initiated, challenge_sent, awaiting_confirmation, under_review, verified_keyed, disputed, withdrawn, rejected, expired, revoked); the reason field carries the last structured transition reason (e.g. GATE_AUTO_APPROVED).

Tiers

Keyed = the claimant proved control of an on-file contact. Internal state; no public badge. Anchored = Keyed plus domain control or accepted documents; the only tier with a public "Verified business" badge and cross-directory federation. Federation is seam-only in v1a: the federation field in status responses is a placeholder list.

Machine-readable contract: GET /api/openapi.json.