Bulk-capture attested consent
Capture up to 1000 attested consent records in one call. Each record is
processed independently, so one bad record does not reject the rest. The
response returns an accepted count plus a rejected array indexed
against your input.
Per-record validation matches the single endpoint at POST /v1/consent.
The plan-gate (PAYG passes; dormant legacy tiers need growth+)
and per-organization rate limiting also match the
single endpoint, with one difference: a bulk call counts
against the rate limit by the number of records in the body. A batch
larger than your per-minute allowance returns 422 VALIDATION_FAILED
with a details.records hint to split the batch.
The request body is capped at 8 MiB; an empty records array returns
422 VALIDATION_FAILED.
Requires the consent:write scope.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Header Parameters
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/consent/bulk" \ -H "Content-Type: application/json" \ -d '{ "records": [ { "phone_number_id": "7c1f0a2d-9e8b-4c3a-9d2e-1f0a2b3c4d5e", "contact_number": "+15554443333", "opted_in": true, "evidence": { "captured_at": "2026-04-26T12:00:00Z", "ip_address": "203.0.113.42", "user_agent": "Mozilla/5.0", "agreement_text": "By signing up you agree to receive appointment reminders. Reply STOP to opt out.", "form_url": "https://example.com/signup", "consent_method": "checkbox" } }, { "phone_number_id": "7c1f0a2d-9e8b-4c3a-9d2e-1f0a2b3c4d5e", "contact_number": "+15554443334", "opted_in": true, "evidence": { "captured_at": "2026-04-26T12:00:01Z", "ip_address": "", "user_agent": "Mozilla/5.0", "agreement_text": "By signing up you agree to receive appointment reminders. Reply STOP to opt out.", "form_url": "https://example.com/signup", "consent_method": "checkbox" } } ] }'{
"accepted": 1,
"rejected": [
{
"index": 1,
"code": "VALIDATION_FAILED",
"reason": "evidence.ip_address: must be a valid IP address"
}
]
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "PLAN_REQUIRED",
"message": "Tier 3 consent capture requires Growth or higher; use double-opt-in (POST /v1/consent/double-opt-in) or the hosted form (POST /v1/consent/hosted) on Starter",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "not found",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "rate limited",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}