---
title: "Record SMS consent"
method: POST
path: "/contacts/{id}/sms-consent"
tags: ["SMS"]
---

# Record SMS consent

`POST /contacts/{id}/sms-consent`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/contacts/{id}/sms-consent`
- Auth: HTTP bearer

Record an SMS opt-in or opt-out that a recipient gave you — typically a checkbox on your own signup form. This is the supported way to bring consent you already hold into Unitpost so marketing SMS is accepted for that contact.

`source` is required: consent without recorded provenance is not consent, and the source is what makes the audit trail defensible. `occurred_at` may be backdated to when the recipient actually agreed (do not pretend historical consent happened just now); a future timestamp is rejected. Every call appends an immutable event, so the history is never overwritten.

Recording an opt-out suppresses SMS for this contact only — it does not touch their email subscription. Requires the `contacts:write` capability.

## Request body

- SmsConsentRecord
  - `action` 'opt_in' | 'opt_out', required
  - `source` 'web_form' | 'hosted_form' | 'keyword' | 'qr' | 'verbal' | 'paper' | 'api_import' | 'api', required
  - `purpose` 'marketing' | 'transactional'
  - `phone` string
  - `occurred_at` string, date-time
  - `evidence_url` string, uri
  - `disclosure_version` string

## Response `201`

The recorded consent event.

- SmsConsentRecorded
  - `object` 'sms_consent', required
  - `phone` string, required
  - `recorded` object, nullable, required
    - `id` string, required
    - `action` string, required
    - `source` string, nullable, required
    - `occurred_at` string, required

## Other responses

- `401`: Missing or invalid API key.
- `404`: Contact not found.
- `422`: Validation error, or the contact has no phone number.

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)