Create a verification passcode check
POST
/v1/verify/verifications/check
const result = await bird.verify.verifications.check({
to: { phone_number: "+15551234567" },
code: "123456",
});
console.log(result.success);result = client.verify.verifications.check(
to={"phone_number": "+15551234567"}, code="123456"
)
print(result.success)result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
Code: "123456",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(*result.Success)$result = $bird->verify->verifications->check(
(new VerificationCheckRequest())
->setTo((new VerificationTo())->setPhoneNumber('+15551234567'))
->setCode('123456'),
);
echo $result->getSuccess() ? 'verified' : 'failed';bird verify verifications check 123456 --phone-number +15551234567curl -X POST "https://us1.platform.bird.com/v1/verify/verifications/check" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": {
"phone_number": "+15551234567"
},
"code": "123456"
}'Respuesta200
{
"reason": "incorrect_code",
"verification": {
"id": "vrf_01krdgeqcxet5s7t44vh8rt9mg",
"status": "pending",
"reason": "attempts_exhausted",
"to": {
"email": "user@example.com",
"phone_number": "+15551234567"
},
"channels": [
{
"channel": "email"
}
],
"last_channel": "email",
"created_at": "2026-05-20T09:14:52Z",
"updated_at": "2026-05-25T16:42:01Z"
}
}
Checks a passcode for a recipient and returns the outcome together with the verification's current state. Identify the verification by the same to used to create it; you do not need to store a verification ID.
A wrong or expired passcode returns 200 OK with success: false and a reason such as incorrect_code or expired. success: true means the verification is complete. Each verification reports its final outcome once and cannot be checked again.
An error status is returned only when the check cannot be evaluated. A 404 E13000 means no active verification matched the recipient: either none
exists for it, or the most recent one is already resolved as verified,
expired, or out of attempts. One code covers all of those, so a 404 is not
evidence the recipient failed to verify. Treat your own record of an earlier
success: true as the outcome, and create a new verification only if the
recipient still needs to verify. A 422 indicates an invalid recipient. A
429 means passcodes for a recipient are being checked too quickly.
Cuerpo de la solicitud
to
object
obligatorio
The recipient to verify. Provide an email, a phone_number, or both; at least one is required. The addresses also identify the verification: a check must supply exactly the set used on the create call, so a verification created with both addresses is not found by either one alone.
Mostrar parámetros secundarios
to.email
string
The recipient's email address. Case does not matter; the address is lowercased before use.
to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
code
string
obligatorio
The passcode the recipient received. Passcodes are numeric; submit the digits exactly as delivered. An incorrect value is a normal 200 outcome with success: false. It does not return an error.
Carga de respuesta
success
boolean
obligatorio
Whether the submitted passcode verified this verification. true means the passcode was correct and the verification is now complete; false means it did not verify, and reason says why. A verification that has already reached a final state is no longer checkable and returns 404.
reason
nullable string
Why the check did not succeed:
- incorrect_code: The passcode was wrong and attempts remain.
- expired: The validity window elapsed.
- attempts_exhausted: Too many incorrect attempts were submitted.
null when success is true. Treat unrecognized values as reasons added
later.
Possible values (may grow over time): incorrect_code, expired, attempts_exhausted
verification
object
obligatorio
Mostrar atributos secundarios
verification.id
string
obligatorio
verification.status
string
obligatorio
The verification's current state:
- pending: Awaiting a correct passcode.
- verified: A correct passcode was submitted.
- failed: The verification cannot be completed. Either too many incorrect passcodes were submitted, or no planned channel could deliver one. Read reason to tell those apart.
- expired: The validity window elapsed before a correct passcode.
- canceled: The verification was canceled before completion.
- blocked: A fraud or abuse control stopped the verification.
Possible values: pending, verified, failed, expired, canceled, blocked
verification.reason
nullable string
Why the verification reached its final state, or null while pending and once verified. See the enum for the values it can take.
verification.to
object
obligatorio
The recipient to verify. Provide an email, a phone_number, or both; at least one is required. The addresses also identify the verification: a check must supply exactly the set used on the create call, so a verification created with both addresses is not found by either one alone.
Mostrar atributos secundarios
verification.to.email
string
The recipient's email address. Case does not matter; the address is lowercased before use.
verification.to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
verification.channels
array of object
obligatorio
The channels this verification uses to deliver the passcode, in attempt order: the first entry is tried first and later entries are fallbacks. An email recipient is verified over email; a phone recipient is verified over the phone channels enabled for its destination country, in the order that country's configuration sets.
Mostrar atributos secundarios
verification.channels.channel
string
obligatorio
The channel a passcode is delivered over. Open enum: new channels may be added over time, so treat any unrecognized value as a future channel rather than an error.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
verification.last_channel
nullable string
The channel the most recent passcode was sent on, or null before the first send. Open enum; new channels may be added over time, so treat any unrecognized value as a future channel rather than an error.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
verification.metadata
object
The key/value pairs attached when the verification was created.
verification.expires_at
string
obligatorio
When the verification expires if no correct passcode is submitted first. After this time its status reports expired.
verification.verified_at
nullable string
When the verification was completed, or null if it is not yet verified.
verification.created_at
string
obligatorio
verification.updated_at
string
obligatorio
attempts_remaining
nullable integer
The number of check attempts left while the verification is still pending, or null once it has reached a final state.
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.
Watch the guideVerify phone numbers at signupUnderstand the conceptWhat does OTP mean? One-time passwords explainedExplore the capabilityCustomer verificationFollow the learning pathBuild your first integration
Try the practice and get an implementation brief