Start a double-opt-in challenge
Send a CTIA-compliant YES/CONFIRM challenge SMS to a contact and open a
pending consent challenge. When the contact replies with confirmation,
AgentMessage records the opt-in with a consent method of double_opt_in.
Idempotent on the combination of organization, phone number, and contact number:
- An open challenge for the same combination returns
200 OKwith the existing pending id andreused=true; no second SMS is sent. - A contact already opted in returns
200 OKwithalready_opted_in=trueand no SMS is sent. - A new challenge returns
202 Acceptedwith the queued confirmation message id, which you can correlate withGET /v1/messages/{id}to track delivery.
An optional Idempotency-Key header is accepted and capped at 255 bytes.
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
curl -X POST "https://example.com/v1/consent/double-opt-in" \ -H "Content-Type: application/json" \ -d '{ "phone_number_id": "7c1f0a2d-9e8b-4c3a-9d2e-1f0a2b3c4d5e", "contact_number": "+15554443333", "confirmation_text": "Reply YES to confirm you\'d like to receive appointment reminders. Reply STOP to opt out, HELP for help.", "agreement_text": "By replying YES you agree to receive appointment reminders from Agentmessage. Msg & data rates may apply. Reply STOP to opt out." }'{
"consent_pending_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
"confirmation_message_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b5",
"expires_at": "2026-04-27T12:00:00Z",
"reused": true,
"already_opted_in": false
}{
"consent_pending_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
"confirmation_message_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b5",
"expires_at": "2026-04-27T12:00:00Z",
"reused": false,
"already_opted_in": false
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"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"
}
}
}