Verification & messages

Get a verification

Reads the verification with every channel attempt and its cost.

GEThttps://watsy.me/v1/verify/{id}

Get a verification

curl https://watsy.me/v1/verify/5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11 \
  -H "Authorization: Bearer $WATSY_KEY"

Response

{
  "id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
  "object": "verification",
  "mode": "live",
  "phone": "+9647701234567",
  "status": "verified",
  "channel": "telegram",
  "channels": [
    "whatsapp",
    "telegram",
    "sms"
  ],
  "attempts": 1,
  "max_attempts": 5,
  "attempts_remaining": 4,
  "locale": "ar",
  "metadata": {
    "user_id": 8841
  },
  "expires_at": "2026-10-28T10:05:00.000Z",
  "verified_at": "2026-10-28T10:01:12.000Z",
  "created_at": "2026-10-28T10:00:00.000Z",
  "price_milli": 18000,
  "messages": [
    {
      "id": "0b6f6a3e-1c2d-4e5f-8a9b-1c2d3e4f5a6b",
      "object": "message",
      "verification_id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
      "channel": "whatsapp",
      "provider": "meta_cloud",
      "status": "failed",
      "error_code": "whatsapp_131026",
      "price_milli": 0,
      "created_at": "2026-10-28T10:00:00.000Z",
      "updated_at": "2026-10-28T10:00:01.000Z"
    },
    {
      "id": "7e1d2c3b-4a59-4687-9a0b-c1d2e3f4a5b6",
      "object": "message",
      "verification_id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
      "channel": "telegram",
      "provider": "telegram_gateway",
      "status": "sent",
      "error_code": null,
      "price_milli": 18000,
      "created_at": "2026-10-28T10:00:01.000Z",
      "updated_at": "2026-10-28T10:00:02.000Z"
    }
  ]
}

Authorization

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

Headers

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.

Response (200)

application/json

idstringrequired
Verification id (UUID).
objectstringrequired
Always verification.
modestringrequired
Mode of the key that created it.
Values:livetest
phonestringrequired
The normalized E.164 number.
statusstringrequired
Lifecycle state. See the status table.
Values:pendingsentverifiedfailedexpiredcanceled
channelstring | nullrequired
The channel last tried, or the one that delivered.
channelsstring[]required
The requested channel chain, in order.
attemptsintegerrequired
Checks made so far.
max_attemptsintegerrequired
Check limit from the project settings (default 5).
attempts_remainingintegerrequired
Checks left.
localestringrequired
Message language.
Values:aren
metadataobjectrequired
Your metadata as sent, or {}.
expires_atstringrequired
When the code expires.
verified_atstring | nullrequired
When it was verified.
created_atstringrequired
Creation time.
price_milliintegerrequired
Net charge across all attempts, in milli-IQD (1 IQD = 1000).
messagesmessage[]required
One entry per channel tried, in order.
Show child fieldsHide child fields
- idstring
  Id of this channel attempt.
- objectstring
  Always message.
- verification_idstring
  The verification this attempt belongs to.
- channelstring
  Channel.
  Values:whatsapptelegramsms
- providerstring
  Who carried the attempt: meta_cloud (Watsy's WhatsApp number), whatsapp_own (your own number), telegram_gateway, or test in test mode.
- statusstring
  delivered appears once the provider reports delivery (WhatsApp today).
  Values:pendingsentdeliveredfailed
- error_codestring | null
  Provider failure reason, e.g. whatsapp_131026, telegram_PHONE_NUMBER_INVALID or timeout.
- price_milliinteger
  Net charge of this attempt in milli-IQD. A refunded attempt shows 0.
- created_atstring
  Creation time (ISO 8601, UTC).
- updated_atstring
  Last update.

Statuses

Status	Meaning
`pending`	Being sent
`sent`	Code sent, waiting for a check
`verified`	Verified
`failed`	Every channel failed, or attempts ran out
`expired`	Expired before a successful check
`canceled`	Canceled by you

Expired verifications switch to expired when read or by a periodic job, and verification.expired fires. Test keys cannot read live verifications and vice versa (404).