• Verify WhatsApp OTP

Verify WhatsApp OTP

POST https://app.alaaqat.com/api/verifications/{id}/verify

Where id is the verification_id returned by a managed mode Send WhatsApp OTP — that is, a send where you left code out and let us generate it.

A relay mode send issues no verification_id, so there is nothing to verify here: if you supplied the code yourself, you own the verification too.

The token must carry the broadcast-send-otp ability, and this endpoint is not callable from a session (first party) context.

Header

{
    "Accept": "application/json"
}

Body

{
    code: string,
}
Field Required Validation Description
code Required 4 to 15 characters, letters and digits only The code the customer entered.

Response

200 when the code matches, 422 otherwise. Branch on verified, and use status only to decide whether it is worth asking the customer again.

{
    "verified": true,
    "status": "verified",
    "attempts_remaining": 5
}
status Meaning
verified The code matched. The verification is now consumed.
pending Wrong code, but the customer may try again. attempts_remaining says how many times.
failed This verification can never succeed again — attempts exhausted, expired, superseded, or already used.

Semantics

  • Single use. Once a verification succeeds, verifying it again returns failed.
  • Five attempts. A wrong code burns one attempt; the fifth wrong attempt kills the verification, and the correct code stops working from then on.
  • Expiry follows the template. A verification expires after the template's own code_expiration_minutes (5 minutes when the template has no expiry footer), because that is the wording the customer was shown. An expired verification returns failed and does not burn an attempt.
  • Superseded by a resend. Sending a new code to the same recipient on the same template marks the previous verification failed, so only one code is ever live.
  • Scoped to your account. A verification_id belonging to another account returns 404, exactly like one that never existed.

Errors

Status Meaning
403 The token lacks broadcast-send-otp, or the request is not from an API token.
404 No such verification on your account.
422 The code was missing or malformed, or it did not verify (see status).
429 Too many verification attempts from this token, slow down.