Verification & messages

Check a code

Checks the code your user typed. Every check counts as an attempt.

POSThttps://watsy.me/v1/verify/{id}/check

Check a code

curl -X POST https://watsy.me/v1/verify/5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11/check \
  -H "Authorization: Bearer $WATSY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: check-8841-1" \
  -d '{
    "code": "482913"
  }'

Response

{
  "id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
  "object": "verification_check",
  "valid": true,
  "status": "verified",
  "attempts": 1,
  "attempts_remaining": 4,
  "verified_at": "2026-10-28T10:01:12.000Z"
}

Authorization

Authorizationstring (header)required
Bearer followed by your project key: wsy_live_… or wsy_test_….

Headers

Idempotency-Keystring
1 to 255 characters. Makes retries safe for 24 hours. See Idempotency.
X-Request-Idstring
Optional, 8 to 64 characters. Echoed back; generated when missing.

Path parameters

idstring (uuid)required
The verification id returned by POST /v1/verify.

Body

application/json

codestringrequired
The code as typed: 4 to 8 digits. Surrounding spaces are trimmed.

Response (200)

application/json

idstringrequired
Verification id.
objectstringrequired
Always verification_check.
validbooleanrequired
The only field to decide on.
statusstringrequired
Verification state after this check.
Values:pendingsentverifiedfailedexpiredcanceled
attemptsintegerrequired
Checks so far.
attempts_remainingintegerrequired
Checks left.
verified_atstring | nullrequired
When it was verified.

Check rules

Decide on valid only. A wrong code returns 200 with valid: false, not an HTTP error.
At max_attempts the verification is locked as failed, and even the right code is refused after that.
After expiry: valid: false with status: "expired". Canceled or failed verifications return valid: false without counting an attempt.
A code is consumed once: checking a verified verification again returns valid: false with status: "verified".

Send an Idempotency-Key with every check. If the response is lost, retry with the same key to get the original answer.