Record a consent

Explicit transactional consent expires after 7 days by policy; inferred consent must carry its own expiry. Verified explicit consent is what lets a promotional call pass the gate.

Requires the write scope. A key with less gets 403 insufficient_scope.

Authorization

AuthorizationBearer <token>

Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

capturedAt?string

🔴 When the RECIPIENT consented — not when you called this endpoint. Defaults to now, which is correct only for a live capture: importing a back catalogue without this dates every record to the day of the import and makes the 7-day transactional clock meaningless.

e164*string

The number that consented, in E.164.

Match^\+91\d{10,11}$

evidenceRef?string

Where the proof lives — a form submission id, a recording URL, a DCA reference. Tone stores the pointer, never the artefact.

Lengthlength <= 500

expiresAt?string

When the consent lapses. Optional for explicit consent, where policy fills it — capped at seven days for a transactional purpose, otherwise until revoked. REQUIRED for inferred consent, which lasts exactly as long as the relationship, and only you know when that ends; omitting it there is a 422.

kind*string

How the consent arose. explicit is a positive act by the recipient; inferred rests on an existing relationship and MUST carry its own expiresAt. Open set — handle an unrecognised value rather than throwing. Today: explicit, inferred.

Value in

"explicit"
"inferred"

purpose*string

What they consented to be contacted about. Consent is purpose-scoped: a record for one purpose does not satisfy the gate for another. Open set — handle an unrecognised value rather than throwing. Today: promotional, service, transactional, collections.

Value in

"promotional"
"service"
"transactional"
"collections"

scope?string

What the recipient actually agreed to, in their words or yours.

Lengthlength <= 1000

source*string

Which channel captured it. Recorded verbatim and returned in the evidence pack. Open set — handle an unrecognised value rather than throwing. Today: api, web_form, ivr, dtmf, otp, dca, import.

Value in

"api"
"web_form"
"ivr"
"dtmf"
"otp"
"dca"
"import"

Response Body

`application/json`

curl -X POST "https://example.com/v1/consent" \  -H "Content-Type: application/json" \  -d '{    "capturedAt": "2026-08-20T11:02:00Z",    "e164": "+919876543210",    "evidenceRef": "form-sub-88213",    "expiresAt": "2026-08-27T11:02:00Z",    "kind": "explicit",    "purpose": "promotional",    "scope": "Order updates and delivery reminders for orders placed on acme.example.",    "source": "web_form"  }'

{  "data": {    "active": true,    "capturedAt": "2026-08-20T11:02:00Z",    "createdAt": "2026-08-25T09:14:22Z",    "e164": "+919876543210",    "evidenceRef": "form-sub-88213",    "expiresAt": "2026-11-23T09:14:22Z",    "id": "8814",    "kind": "explicit",    "purpose": "promotional",    "revokedAt": null,    "revokedReason": null,    "scope": "Order updates and delivery reminders.",    "source": "api"  }}

Was this page helpful?

Record a consent

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`