Verify (OTP check)

API for creating and verifying one-time passwords (OTP) via SMS, Email and other channels.

POST requests must include the header Content-Type: application/json. Code verification (verify) also supports the GET method.

---

Create code — synchronous

Creates a verification code and sends it via SMS or Email. The gateway processes the request immediately and returns verify_id.

URI: /api/verify.php

HTTP method: POST

Request parameters

authstringrequired API key from your personal cabinet

commandstringrequired Must be verify/create

phonestringrequired* Phone number in any format (required if email is not specified)

emailstringrequired* Email address (required if phone is not specified)

typestringrequired Verification type: sms, hlr, rcs, email, viber

sender_namestring SMS signature / brand name

langstring Message language: uk, ru, en (default en)

code_lengthnumber Code length (default 8, range 1–10)

code_typestring Code type: numeric, alphabetic, alphanumeric, extended (default numeric)

service_idnumber Verification service ID

custom_idstring Custom identifier for linking with your system

hookstring Webhook URL for verification status notifications

Request example

JSON

{
    "auth": "API_KEY",
    "command": "verify/create",
    "phone": "441501234567",
    "type": "sms",
    "sender_name": "MyBrand",
    "lang": "en",
    "code_length": 6,
    "code_type": "numeric",
    "service_id": 1,
    "custom_id": "abcdef1234567",
    "hook": "https://example.com/webhook"
}

cURL

curl -X POST 'https://blackbox.business/api/verify.php' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "auth": "API_KEY",
  "command": "verify/create",
  "phone": "441501234567",
  "type": "sms",
  "sender_name": "MyBrand",
  "lang": "en",
  "code_length": 6,
  "code_type": "numeric",
  "service_id": 1,
  "custom_id": "abcdef1234567",
  "hook": "https://example.com/webhook"
}'

PHP

<?php

$payload = json_encode([
    'auth' => 'API_KEY',
    'command' => 'verify/create',
    'phone' => '441501234567',
    'type' => 'sms',
    'sender_name' => 'MyBrand',
    'lang' => 'en',
    'code_length' => 6,
    'code_type' => 'numeric',
    'service_id' => 1,
    'custom_id' => 'abcdef1234567',
    'hook' => 'https://example.com/webhook',
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://blackbox.business/api/verify.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python

import requests

payload = {
    "auth": "API_KEY",
    "command": "verify/create",
    "phone": "441501234567",
    "type": "sms",
    "sender_name": "MyBrand",
    "lang": "en",
    "code_length": 6,
    "code_type": "numeric",
    "service_id": 1,
    "custom_id": "abcdef1234567",
    "hook": "https://example.com/webhook",
}

response = requests.post(
    "https://blackbox.business/api/verify.php",
    json=payload,
    timeout=30,
)

print(response.json())

Node.js

const payload = {
  "auth": "API_KEY",
  "command": "verify/create",
  "phone": "441501234567",
  "type": "sms",
  "sender_name": "MyBrand",
  "lang": "en",
  "code_length": 6,
  "code_type": "numeric",
  "service_id": 1,
  "custom_id": "abcdef1234567",
  "hook": "https://example.com/webhook"
};

const response = await fetch("https://blackbox.business/api/verify.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(await response.json());

Response

successboolean Result of request acceptance

verify_idstring Verification ID (UUID)

Example response:

{
  "success": true,
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a"
}

HTTP errors: 400 (invalid format/JSON), 401 (invalid auth), 413 (request body too large).

---

Create code — asynchronous

Queues code creation for background processing. Request body is the same as for synchronous create, except the command field is optional (the worker sets verify/create automatically).

URI: /v1/verify/create

HTTP method: POST

Content-Type: application/json

Example response:

{
  "request_id": "cf-ray-1234567890-ABC",
  "success": true
}

verify_id is not returned in this response. If the request is rejected during processing, the reason is delivered to the hook URL — see Webhook. The result of the check itself is obtained with the verify command.

HTTP error codes:

Code	Description
400	Invalid JSON
401	Missing or invalid auth
405	Method other than POST
413	Request body too large
415	Missing or invalid Content-Type (must be application/json)
503	Queue unavailable

---

Verify code

URI: /api/verify.php

This request checks the code entered by the user and returns the verification status (only the sync API).

Request parameters

authstringrequired API key, which can be obtained in your personal cabinet

commandstringrequired Must be verify

phonestringrequired* Phone number (required if email is not specified)

emailstringrequired* Email address (required if phone is not specified)

codestringrequired Code to be checked

verify_idstring Verification ID (UUID)

service_idnumber Verification service ID (if verify_id is not specified)

custom_idstring Custom identifier (if neither service_id nor verify_id is specified)

Request example (GET)

/api/verify.php?auth=API_KEY&command=verify&phone=380501234567&code=123456&verify_id=14fb5f3d-20be-41ef-b31a-b9f5e499bc7a

Request example (POST, JSON)

JSON

{
    "auth": "API_KEY",
    "command": "verify",
    "phone": "380501234567",
    "code": "123456",
    "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a"
}

cURL

curl -X POST 'https://blackbox.business/api/verify.php' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "auth": "API_KEY",
  "command": "verify",
  "phone": "380501234567",
  "code": "123456",
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a"
}'

PHP

<?php

$payload = json_encode([
    'auth' => 'API_KEY',
    'command' => 'verify',
    'phone' => '380501234567',
    'code' => '123456',
    'verify_id' => '14fb5f3d-20be-41ef-b31a-b9f5e499bc7a',
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://blackbox.business/api/verify.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python

import requests

payload = {
    "auth": "API_KEY",
    "command": "verify",
    "phone": "380501234567",
    "code": "123456",
    "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a",
}

response = requests.post(
    "https://blackbox.business/api/verify.php",
    json=payload,
    timeout=30,
)

print(response.json())

Node.js

const payload = {
  "auth": "API_KEY",
  "command": "verify",
  "phone": "380501234567",
  "code": "123456",
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a"
};

const response = await fetch("https://blackbox.business/api/verify.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(await response.json());

Response

successboolean Result of the request

verify_idstring Verification ID

phonestring Phone number

typestring Channel type: sms, email, hlr, rcs, viber

statusstring Verification status (see below)

service_idnumber Verification service ID

Example of a successful response:

{
  "success": true,
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a",
  "phone": "441501234567",
  "type": "sms",
  "status": "approved",
  "service_id": 1
}

Possible values of status:

status	Description
approved	Code is correct, verification successful
pending	Code is incorrect, but attempts are still available
expired	Code has expired
blocked	Attempt limit exceeded

HTTP error codes:

• 400 — invalid request format or JSON
• 401 — missing or invalid auth
• 413 — request body too large

---

Webhook

If the hook parameter was passed and the request was rejected during processing, the gateway sends a notification to that address.

The payload repeats the format of the message webhook: a flat object with status and the reason in error. There is no separate payload for errors.

HTTP method: POST
Content-Type: application/json
X-Signature: sha256(json_body + api_key)

Parameter	Type	Description
verify_id	string	Identifier of the verification
status	string	Always REJECTED — the request was rejected during processing
error	string	Reason why the request was rejected
updated	string	Date and time of the event Format: YYYY-MM-DDThh:mm:ss±hh:mm
request_id	string	Identifier of the request, returned by the asynchronous API

Request example

{
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a",
  "status": "REJECTED",
  "error": "Access denied",
  "updated": "2026-08-21T10:12:33+03:00",
  "request_id": "a1436d496bf11a59"
}

Response

You will receive code 200 in response. The webhook is sent once, without retries.

---

Limits

• Code lifetime: by default 300 seconds (5 minutes), range 60–3600 seconds.
• Maximum attempts: by default 5.