TrueNum API

TrueNum подтверждает принадлежность телефонного номера по входящему звонку (Caller-ID). Абонент звонит со своего телефона на выданный нами номер; мы фиксируем номер звонящего и подтверждаем владение. Вводить код, как в SMS-OTP, не нужно — достаточно совершить звонок. Это дешевле SMS и короче по UX.

Как это работает

sequenceDiagram
    autonumber
    participant Client as Ваш бэкенд
    participant API as TrueNum API
    participant User as Пользователь
    Client->>API: POST /api/v1/verifications/ {phone, webhook_url}
    API-->>Client: 201 {verification_id, dial_number, expires_at}
    Client->>User: «Позвоните на dial_number»
    User->>API: Звонок с phone на dial_number
    API-->>Client: POST webhook_url {type, caller_id} + подпись

Полный цикл — 10–30 секунд. Если за TTL (по умолчанию 5 минут) звонок не поступил, мы отправляем verification.expired.

Ключевые свойства

• Два эндпоинта: создать верификацию и прочитать её статус.
• Подписанные вебхуки — HMAC-SHA256, заголовок X-Truenum-Signature.
• TTL по умолчанию 5 минут (эффективный диапазон 30–600 секунд).
• SSRF-защита webhook_url: приватные и loopback-адреса отклоняются.
• Лимит 120 запросов в минуту на API-ключ.

С чего начать

• Быстрый старт — от регистрации до первой успешной верификации за 10 минут.
• Обзор API — базовый URL, формат, версионирование.
• Аутентификация — Bearer-токены tn_live_*.
• Верификации — оба эндпоинта с примерами.
• Webhooks — приём событий и проверка подписи.

Интерактивная схема

Живой Swagger UI и сырая OpenAPI-схема доступны на боевом хосте: /api/docs/ и /api/schema/.

Поддержка

Вопросы по API — на адрес поддержки, указанный в дашборде вашего аккаунта.