Request and check a code

Request a code

POST /v1/verify creates a session and queues the code for sending. Response 201. Only the phone field is required.

{
  "phone": "+77011234567",
  "purpose": "login",
  "signals": {
    "ip": "95.56.1.1",
    "device_id": "3f2c9a71",
    "device_platform": "ios",
    "device_model": "iPhone 16",
    "os_version": "26.1",
    "app_version": "2.4.0",
    "user_agent": "MyApp/2.4.0",
    "is_trusted_user": false
  },
  "options": {
    "locale": "ru",
    "code_size": 4,
    "preferred_channel": "telegram"
  },
  "metadata": { "correlation_id": "order-42" }
}

Field	Values
phone	Kazakhstan mobile number: +77XXXXXXXXX, 77… or 87…. Spaces, parentheses and hyphens are allowed
purpose	login (default) or registration
signals.ip	The user’s IPv4 or IPv6 address
signals.device_id	Device identifier, up to 128 characters
signals.device_platform	android, ios or web
signals.device_model	Up to 64 characters
signals.os_version, signals.app_version	Up to 32 characters
signals.user_agent	Up to 300 characters
signals.is_trusted_user	true removes the per-number session limit and your account’s antifraud rules
options.locale	Message language: ru (default), kk or en
options.code_size	Code length, from 4 to 8 digits. Overrides the account setting
options.custom_code	Your own code of 4–8 digits instead of a random one
options.preferred_channel	Start with the telegram, whatsapp or sms channel. See channels for details
metadata.correlation_id	Your identifier, up to 80 characters. Included in the statement, CSV and webhooks

Pass signals if you have them: antifraud counts limits by IP and device, and without them these rules do not work. Long text signals are truncated; the request is not rejected because of them.

Response:

{"id": "vrf_8c1f04a2b7d93e6f5a10", "status": "pending", "expires_at": "2026-11-08T10:05:00Z"}

For a test number, the response also includes "test": true. There is no channel in this response: VERYO picks it later.

Check a code

POST /v1/verify/check takes the session id and the code the user entered. Response 200.

{"id": "vrf_8c1f04a2b7d93e6f5a10", "code": "1234"}

{"id": "vrf_8c1f04a2b7d93e6f5a10", "status": "verified", "channel": "telegram"}

status	What it means	What to do
pending	The code is wrong, attempts remain	Ask the user to enter the code again
verified	The code is verified. A repeat call also returns verified	Let the user through
failed	Entry attempts or delivery channels ran out	Request a new code
expired	The code has expired	Request a new code

channel is the channel that delivered the code: telegram, whatsapp or sms. The field is absent until the code is delivered, and for test numbers.

Sessions from another account and nonexistent id values return 404 not_found.

Code settings

Defaults are changed in the dashboard, in the Code & SMS section.

Setting	Range	Default
Code length	4–8 digits	4
Validity period	1–30 minutes	5 minutes
Entry attempts	1–10	3
Sessions per number	1–50	4
Session limit window	1–168 hours	72 hours
Cancel the previous code on a new request	yes or no	no

Resending a code

To send a code again, call POST /v1/verify again. This is a new session with a new id and a new code, so:

• it is charged separately when delivered;
• it counts toward the per-number session limit, and if the limit is exceeded the API returns 429 rate_limited;
• the previous code stays valid until it expires, unless the cancellation setting is on.