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. On WhatsApp the user receives the code over chat (after opening the send’s action_url) and enters it here the same way. 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.