# Record a consent

Source: https://docs.usetone.ai/reference/compliance/consent.record

> Explicit transactional consent expires after 7 days by policy; inferred consent must carry its own expiry.

`POST /v1/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.

## Request body

| Field | Type | | Meaning |
|---|---|---|---|
| `capturedAt` | string | optional | 🔴 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 | required | The number that consented, in E.164. |
| `evidenceRef` | string | optional | Where the proof lives — a form submission id, a recording URL, a DCA reference. Tone stores the pointer, never the artefact. |
| `expiresAt` | string | optional | 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 | required | 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`. |
| `purpose` | string | required | 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`. |
| `scope` | string | optional | What the recipient actually agreed to, in their words or yours. |
| `source` | string | required | 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`. |

### Example request

```json
{
  "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"
}
```

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `active` | boolean | required | Whether this record satisfies the gate right now. |
| `capturedAt` | string | required | When the RECIPIENT consented, not when you told us. |
| `createdAt` | string | required | When this consent was recorded with Tone, RFC 3339 UTC. Distinct from `capturedAt`, which is when the recipient actually consented. |
| `e164` | string | required | The number that consented, in E.164. |
| `evidenceRef` | string | null | required | Where the proof lives — form id, recording URL, DCA reference. |
| `expiresAt` | string | null | required | When the consent lapses. RFC 3339, UTC. Null means it stands until revoked. |
| `id` | string | required | The consent record’s id. Pass it to `POST /v1/consent/{id}/revoke` to revoke this one record. |
| `kind` | string | required | Open set — handle an unrecognised value rather than throwing. Today: `explicit`, `inferred`. |
| `purpose` | string | required | What they consented TO. Open set — handle an unrecognised value rather than throwing. Today: `promotional`, `service`, `transactional`, `collections`. |
| `revokedAt` | string | null | required | The ledger is append-only; revocation is a stamp, not a delete. |
| `revokedReason` | string | null | required | Why the consent was revoked, when a reason was given. |
| `scope` | string | null | required | What the recipient agreed to, as it was recorded. |
| `source` | string | required | Weakest to strongest as evidence. Open set — handle an unrecognised value rather than throwing. Today: `api`, `web_form`, `ivr`, `dtmf`, `otp`, `dca`, `import`. |

### Example response

```json
{
  "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"
  }
}
```