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
- Initiate.
POST /api/v1/claimswith your tenant API key (scopeclaims.initiate), the tenant's listing reference, and the principal you act for. Include anIdempotency-Keyheader — 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. - 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. - 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.
- Poll status.
GET /api/v1/claims/{id}/status(scopeclaims.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.