Verification
A Verification represents a one-time code (OTP) session used to confirm a user action, for example confirming a phone number during subscription creation.
Your integration creates a Verification, Connect delivers a code to the recipient over SMS, and your integration then submits the code the user provides for validation. The session tracks how many attempts have been made and enforces a time-to-live so codes cannot be used indefinitely.
Session lifecycle
Each Verification is a short-lived session that moves through the following states:
- pending: the session is active and waiting for the code to be verified. It stays in this state while the code is unverified and the time-to-live and attempt limits have not been exceeded. Submitting an incorrect code keeps the session
pendingand increments the attempt counter. - verified: the correct code was submitted. Terminal state, the session cannot be reused.
- failed: the session has expired or the maximum number of verification attempts has been reached. Terminal state, the session cannot be reused.
Once a session is verified or failed, no further operations on it are allowed.
Per-partner configuration
The following behaviors are configured per partner during onboarding:
| Setting | Purpose |
|---|---|
| Code TTL | How long the generated code remains valid (in seconds) |
| Rate limit window | The time window over which rate limits are applied |
| Rate limit max requests | Maximum create-session requests allowed within the rate limit window |
| Max check attempts | Maximum number of verification attempts per session |
| Sender name | The name shown to the recipient in the OTP message |
| Message template | The template used to build the verification message |
Contact your onboarding representative to review or change these values.
Rate limiting
Create-session requests are rate-limited per recipient and partner. When the limit is exceeded, Connect responds with 429 Too Many Requests and the following headers so your integration can back off:
X-Rate-Limit-Limit: the ceiling that applied to this requestX-Rate-Limit-Remaining: remaining allowance in the current windowX-Rate-Limit-Reset: Unix timestamp (milliseconds) at which the window resets
Error codes
When a verification attempt cannot proceed, the response includes one of the following error codes:
| Code | Meaning |
|---|---|
invalid_code | The submitted code does not match the one issued for the session |
expired_code | The session's time-to-live has elapsed |
max_attempts_exceeded | The maximum number of verification attempts has been reached |
rate_limit_exceeded | The partner has exceeded the allowed rate of create-session requests |
expired_code and max_attempts_exceeded transition the session to failed.
API Reference
See the full list of endpoints, request and response schemas, examples, and version information in the Verifications section of the API Reference.