---
title: "Record a consent event"
method: POST
path: "/consents"
tags: ["Compliance & Consent"]
---

# Record a consent event

`POST /consents`

## Request

- Base URL: `https://api.envoisms.ma/v1`
- URL: `https://api.envoisms.ma/v1/consents`
- Auth: HTTP bearer

Records that a person granted or withdrew consent, with the evidence you
hold (the wording shown, the page URL, the IP, a reference). `recorded_at`
may be backdated for an imported consent; it cannot be in the future.
A `marketing` withdrawal is also placed on the opt-out list immediately.

`source` is limited to `api`, `form`, `import` and `dashboard`: the
keyword and inbound sources are the platform's own observations and are
reserved.

## Request body

- object
  - `phone` string, required
  - `purpose` 'marketing' | 'transactional' | 'otp' | 'service', required
  - `status` 'granted' | 'withdrawn'
  - `channel` 'whatsapp' | 'sms' | 'any'
  - `source` 'api' | 'form' | 'import' | 'dashboard'
  - `evidence` object: Free-form JSON object under 4 KB — the wording shown, url, ip, reference
  - `recorded_at` string, date-time: When the person acted (defaults to now; may be backdated, never in the future)

## Response `201`

Event recorded

- ConsentEvent
  - `id` string
  - `phone` string
  - `channel` 'whatsapp' | 'sms' | 'any'
  - `purpose` 'marketing' | 'transactional' | 'otp' | 'service'
  - `status` 'granted' | 'withdrawn'
  - `source` 'api' | 'form' | 'import' | 'dashboard' | 'whatsapp_keyword' | 'sms_keyword' | 'whatsapp_inbound' | 'ctwa'
  - `evidence` object, nullable
  - `recorded_at` string, date-time
  - `created_at` string, date-time

## Other responses

- `400`: INVALID_PHONE, INVALID_PURPOSE, INVALID_STATUS, INVALID_CHANNEL, INVALID_SOURCE, INVALID_EVIDENCE or INVALID_DATE

---

[API](https://skmtc.dev/envoisms/apis/envoisms-ma-api.md) · [All operations](https://skmtc.dev/envoisms/apis/envoisms-ma-api/llms.txt) · [OpenAPI document](https://skmtc.dev/envoisms/apis/envoisms-ma-api/revisions/662db074bd86?raw)