POST /otp/verify

Check a code the user entered against a previously sent otp_id. matched is true only on the correct code. A wrong code keeps the OTP pending until attempts are exhausted, then failed.

Run send first to get an otp_id. In the sandbox, the accepted code is always 123456.

This endpoint works for every channel, WhatsApp included. In the default WhatsApp mode the user receives the code over chat (after opening the send’s action_url) and enters it here the same way. The one exception is an OTP whose send came back with completion: "inbound": it is approved by the user’s own WhatsApp message and has no code to verify, so watch status or the webhook instead. See WhatsApp verification.

The otp.approved webhook fires on approval if you prefer a push signal over this response.

curl -X POST https://api.otp.com/api/v1/otp/verify \
  -H "Authorization: Bearer otp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{"otp_id":"9f3c1b2a-…","code":"123456"}'

Request body

Field	Type	Required	Description
otp_id	string	yes	The id returned by send.
code	string	yes	The code the user entered.

Response

{
  "otp_id": "9f3c1b2a-…",
  "status": "approved",
  "matched": true
}

Field	Description
matched	true if the code was correct.
status	approved on a match; otherwise pending (attempts remain) or failed (exhausted).

Common errors

Status	Type	When
404	HTTPException	otp_id not found, or not on your company.
422	ValidationError	Missing or malformed request body.

See Error codes for the full list.