Verifications
Learn the verification fields, lifecycle, code checks, and sender-profile rate limits.
A verification represents one code request. The code is generated by Maileroo and is never returned by the API. Its identifier has the vrf_ prefix.
Verification fields
| Field | Type | Description |
|---|---|---|
id | string | Verification identifier. |
account_id | string | Account that owns the verification. |
sender_profile_id | string | Sender profile used for the request. |
channel | string | sms, voice, whatsapp, telegram, or email. |
to | string | Normalized phone number or email destination. |
country | string | Country code when available. |
code_length | integer | Number of digits in the generated code. |
status | string | Current lifecycle state. |
attempts | integer | Number of well-formed code checks made. |
max_attempts | integer | Maximum number of checks allowed for this verification. The response reports the applicable value. |
expires_at | string | RFC3339 time after which the code can no longer be checked. |
verified_at | string | Present after a code is successfully verified. |
created_at | string | RFC3339 time the verification was created. |
updated_at | string | RFC3339 time the verification was last updated. |
Verification responses do not include the code. List results are history rows and omit updated_at.
Lifecycle statuses
| Status | Meaning |
|---|---|
pending | The request was accepted and delivery has not yet been marked sent. |
sent | The send succeeded. The code may still be checked until it expires. |
verified | The submitted code matched. |
expired | The verification passed its expires_at time. |
failed | Delivery failed or the maximum number of checks was reached. |
cancelled | The verification was cancelled. |
Check results
POST /verifications/:id/check returns a separate result status:
| Result | Meaning |
|---|---|
approved | The code was verified. The verification status is verified. |
incorrect | The code did not match; attempts_remaining reports the remaining checks. |
expired | The verification has expired. |
failed | Delivery failed or no more checks are allowed. |
cancelled | The verification was cancelled. |
Each well-formed code check increments attempts, whether it is correct or incorrect. A code must contain the number of digits shown by code_length; malformed codes return 400 and do not consume an attempt. When the maximum is reached, the verification becomes failed. attempts_remaining is nonzero only for an incorrect result.
Expiration and rate limits
expires_at is set when the verification is created. You can choose expires_in in the create request; otherwise, the service applies its current expiration setting. A check after expiration returns the expired result.
A sender profile can limit how many verifications are created within a rolling window_seconds, either per destination and channel or across the whole profile. When that limit is reached, creating a verification returns 429 Too Many Requests.