Record a consent event
POST /v1/consent-records
| Property | Value |
|---|---|
| Operation | create_consent_record |
| Group | Consent |
| Scope | consent:write |
| Route class | control |
| Idempotency | Idempotency-Key accepted: a retry with the same key replays the first answer |
| Audit | Audited contacts.consent.record (mutation) |
| Released in | 1.61.0 |
| Phase 0 host | Served (the hosted api pins 1.65.0) |
Appends one record to the consent ledger and sets the derived state in the same transaction (1.61.0), so the next admission and the next send read it; writes consent.changed. Under the Compliance profile's revocation_scope: all_channels an Organization-scope opt-out sets every address channel of the address (applied_channels). An opt-in or a grant over an opt-out without evidence is validation_failed (consent_evidence_required); the channel app_push and the purpose marketing are capability_not_available. The Audit event names the channel, scope and state, never the address.
Request
Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the consent:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.
curl -X POST "$VOCAL_API/v1/consent-records" \
-H "Authorization: Bearer $VOCAL_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "channel": "voice", "state": "opted_in" }'const response = await fetch(`${process.env.VOCAL_API}/v1/consent-records`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
"channel": "voice",
"state": "opted_in"
}),
});
console.log(response.status, await response.text());import os
import uuid
import requests
response = requests.post(
f"{os.environ['VOCAL_API']}/v1/consent-records",
headers={
"Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"channel": "voice",
"state": "opted_in",
},
)
print(response.status_code, response.text)Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
idempotency-key | header | string | no | A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response. |
Request body
Content type application/json, required: ConsentRecordCreateRequest.
| Field | Type | Required | Description |
|---|---|---|---|
address | ConsentAddress | no | The address; required for every channel but memory, refused for memory. |
basis | ConsentBasis | no | Required for opted_in and granted, refused for opted_out and revoked. |
channel | ConsentChannel | yes | |
contact_id | ContactId | no | The Contact; required for memory, whose subject is a Contact. For an address channel it only links the record, and the Contact must hold the address (consent_contact_unknown otherwise). |
evidence | ConsentEvidenceInput | no | Required for an opt-in or a grant over an opted_out or revoked state (consent_evidence_required). |
occurred_at | RequestTimestamp | no | When the person acted; when the api records it if omitted. |
purpose | ConsentPurpose | no | all when omitted. |
scope | ConsentScope | no | organization when omitted. |
sender | ConsentSenderInput | no | Required with scope: sender, refused otherwise. |
state | ConsentStateValue | yes | An address channel takes opted_in or opted_out, memory takes granted or revoked. |
Responses
| Status | Content type | Shape | Error codes |
|---|---|---|---|
201 | application/json | ConsentRecord | |
400 | application/json | ErrorEnvelope | invalid_request |
401 | application/json | ErrorEnvelope | unauthenticated |
403 | application/json | ErrorEnvelope | forbidden, org_suspended |
409 | application/json | ErrorEnvelope | idempotency_in_progress, idempotency_key_reused |
422 | application/json | ErrorEnvelope | validation_failed, capability_not_available |
429 | application/json | ErrorEnvelope | rate_limited |
500 | application/json | ErrorEnvelope | internal_error |
Fields of the 201 answer
The shape is ConsentRecord.
| Field | Type | Required | Description |
|---|---|---|---|
applied_channels | array of ConsentChannel | yes | The channels whose state the record set: the channel itself, and under revocation_scope: all_channels every address channel of an Organization-scope opt-out. |
basis | ConsentBasis or null | yes | |
channel | ConsentChannel | yes | |
contact_id | ContactId or null | yes | The Contact the record names or whose identity holds the address; or null. |
environment | Environment | yes | |
evidence | ConsentEvidence or null | yes | |
id | ConsentRecordId | yes | |
identity_id | ContactIdentityId or null | yes | The identity of that Contact that holds the address; null for memory. |
object | "consent_record" | yes | |
occurred_at | Timestamp | yes | |
purpose | ConsentPurpose | yes | |
recorded_at | Timestamp | yes | |
recorded_by | ActorRef | yes | |
scope | ConsentScope | yes | |
sender | ConsentSender or null | yes | |
source | ConsentSource | yes | |
state | ConsentStateValue | yes |