Create a refusal check
Requires a configured delivery time zone and follow-up texts for the exact language. Use an APPROVED, standard UTILITY template with no header or a text header and only the required quick-reply buttons. Parameters must match the template count/names. The refusal template has exactly two buttons, in order: yes (I refused), no (I did not). The original confirmation must have a conversation and be neither accepted nor failed. At most one refusal check is allowed per confirmation, using its original sender and recipient.
One accepted request consumes one unit of the separate monthly refusal allowance.
Idempotency-Key applies to refusal checks in your workspace, separately from other POST operations. Repeated requests must match confirmationId and all body fields to return the original acceptance.
Unknown query parameters are rejected. Unknown body fields are rejected. All examples use fictional values.
Responses
| Status | Meaning and codes |
|---|---|
| 202 | Accepted. Completion is asynchronous. |
| 401 | Problem Details. Codes: API_KEY_INVALID. |
| 404 | Problem Details. Codes: COD_SENDER_NOT_FOUND, COD_TEMPLATE_NOT_FOUND, COD_CONFIRMATION_NOT_FOUND. |
| 409 | Problem Details. Codes: COD_NOT_CONFIGURED, COD_LANGUAGE_NOT_CONFIGURED, COD_SENDER_UNAVAILABLE, COD_TEMPLATE_NOT_USABLE, IDEMPOTENCY_KEY_REUSED, COD_CONFIRMATION_NOT_ELIGIBLE, COD_REFUSAL_CHECK_EXISTS. |
| 422 | Problem Details. Codes: DEVELOPER_INVALID_INPUT, COD_TEMPLATE_PARAMETERS_INVALID, RECIPIENT_BLOCKED. |
| 429 | Problem Details. Codes: RATE_LIMITED, COD_QUOTA_EXCEEDED. Retry-After: 1 is present only for RATE_LIMITED; quota errors do not include it. |
Success and handled error responses send Cache-Control: no-store and X-Correlation-ID (the resolved/generated UUID). Errors use application/problem+json and the reusable ProblemDetails schema below. Retry-After: 1 is sent only for RATE_LIMITED. Request examples read your key from a server environment variable; replace all fictional values.
Schemas and examples
ApiKeyAuthorizationBearer <token>Server-side API key. publicId is 12 lowercase base32 characters (a-z, 2-7); secret is 43 base64url characters from 32 random bytes. Use Authorization: Bearer <complete key>. The API key determines the workspace; requests cannot select another workspace. All public routes share 20 requests per second per key. See API-key authentication.
confirmationId*stringConfirmation ID in your workspace, returned when you create a COD confirmation.
uuidIdempotency-Key?stringOptional string of at most 128 characters. Empty string is accepted by validation; use a unique non-empty value per request. Save it and reuse it if you are unsure whether the request succeeded. See each operation for which values must match on repeated requests.
length <= 128X-Correlation-ID?stringOptional tracing ID. A UUID-shaped value is echoed in the response. Missing or invalid values are replaced with a generated UUID, not rejected.
application/json- body
template*parameters?Accepted. Completion is asynchronous.
application/json- response
confirmationId*stringOriginal confirmation UUID.
uuidrefusalCheck*