CheckAccount REST API для MAX: пример Python, Node и cURL

REST API — обязательный инструмент для команд, которые встраивают проверку номеров в продакшен-pipeline: антифрод на регистрации, обогащение CRM в реальном времени, sales-инструменты, ML-модели скоринга. Веб-форма с CSV — для разовых задач, API — для систем.

Эта статья — полная документация REST API нашего сервиса checkmaxapp.com: endpoints, форматы, примеры на трёх языках, batch-режим, webhooks, rate-limits, обработка ошибок.

TL;DR

• POST /v1/check-account — одиночная проверка, ответ 200–500 мс
• POST /v1/check-account/batch — массовая проверка до 10 000 за запрос
• Возвращает registered, firstName, lastName, server_id, last_seen, bio
• Авторизация: Authorization: Bearer YOUR_TOKEN
• Rate-limits: 100/мин одиночных, 10/час batch
• Webhook для асинхронных batch-результатов
• Цена та же, что и через бот: $0.005 за hit, со скидками до 40%

Получение токена

API-токен выдаётся в личном кабинете на checkmaxapp.com после регистрации. Бесплатные 5 проверок доступны без депозита — протестировать API можно сразу. Дальше пополнение от $10 (тарифы и скидки).

Храните токен в переменных окружения, не коммитьте в репозиторий. Минимально:

export MAXCHECK_TOKEN="sk_live_..."

Endpoint: одиночная проверка

Запрос

POST https://api.checkmaxapp.com/v1/check-account
Headers:
  Authorization: Bearer YOUR_TOKEN
  Content-Type: application/json
Body:
  { "phone": "+79161234567" }

Номер строго в формате E.164: знак +, код страны, без пробелов и дефисов. Подробнее про нормализацию — Как очистить базу 100k.

Ответ при registered=true

{
  "phone": "+79161234567",
  "registered": true,
  "firstName": "Анна",
  "lastName": "Иванова",
  "server_id": 847291,
  "last_seen": "2026-05-11 09:42:15",
  "bio": "Маркетолог, Москва",
  "checked_at": "2026-05-11T12:33:21Z"
}

Ответ при registered=false

{
  "phone": "+79161234567",
  "registered": false,
  "checked_at": "2026-05-11T12:33:21Z"
}

Когда registered=false — пользователя в MAX нет, остальные поля не возвращаются. Деньги списываются только за положительные hits (registered=true), отрицательные ответы бесплатные.

Пример: cURL

curl -X POST https://api.checkmaxapp.com/v1/check-account \
  -H "Authorization: Bearer $MAXCHECK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+79161234567"}'

Полезно для быстрых проверок и интеграционных скриптов.

Пример: Python (requests)

Синхронный клиент для простых сценариев:

import os
import requests

TOKEN = os.environ["MAXCHECK_TOKEN"]
URL = "https://api.checkmaxapp.com/v1/check-account"

def check_phone(phone: str) -> dict:
    response = requests.post(
        URL,
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Content-Type": "application/json",
        },
        json={"phone": phone},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = check_phone("+79161234567")
    if result["registered"]:
        print(f"Найден: {result.get('firstName')} {result.get('lastName')}")
    else:
        print("Не зарегистрирован в MAX")

Пример: Python async (httpx)

Для высокой пропускной способности — асинхронный клиент:

import asyncio
import os
import httpx

TOKEN = os.environ["MAXCHECK_TOKEN"]
URL = "https://api.checkmaxapp.com/v1/check-account"

async def check_phone(client: httpx.AsyncClient, phone: str) -> dict:
    r = await client.post(
        URL,
        headers={"Authorization": f"Bearer {TOKEN}"},
        json={"phone": phone},
        timeout=10.0,
    )
    r.raise_for_status()
    return r.json()

async def main(phones: list[str]):
    async with httpx.AsyncClient(http2=True) as client:
        tasks = [check_phone(client, p) for p in phones]
        results = await asyncio.gather(*tasks, return_exceptions=True)
    return results

if __name__ == "__main__":
    phones = ["+79161234567", "+79162345678", "+79163456789"]
    print(asyncio.run(main(phones)))

При больших объёмах вместо много параллельных одиночных запросов лучше использовать batch endpoint (см. ниже) — это дешевле по rate-limits.

Пример: Node.js (fetch)

Современный нативный fetch (Node.js 18+):

const TOKEN = process.env.MAXCHECK_TOKEN;
const URL = 'https://api.checkmaxapp.com/v1/check-account';

async function checkPhone(phone) {
  const response = await fetch(URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ phone }),
  });
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
  return response.json();
}

(async () => {
  const result = await checkPhone('+79161234567');
  console.log(result);
})();

Пример: Node.js (axios)

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.checkmaxapp.com',
  headers: { Authorization: `Bearer ${process.env.MAXCHECK_TOKEN}` },
  timeout: 10000,
});

async function checkPhone(phone) {
  const { data } = await client.post('/v1/check-account', { phone });
  return data;
}

checkPhone('+79161234567').then(console.log);

Batch endpoint

Для проверки от 100 номеров за раз — asynchronous batch:

Запрос

POST https://api.checkmaxapp.com/v1/check-account/batch
Headers:
  Authorization: Bearer YOUR_TOKEN
  Content-Type: application/json
Body:
  {
    "phones": ["+79161234567", "+79162345678", ...],
    "callback_url": "https://your-app.com/maxcheck-webhook"
  }

Лимит: 10 000 номеров за один запрос. Для больших объёмов разбивайте на батчи. Пропускная способность сервера — до 1 млн номеров в час.

Ответ

Сервер сразу возвращает job_id:

{
  "job_id": "job_8x4kpqz2nm",
  "status": "queued",
  "phones_count": 10000,
  "estimated_completion": "2026-05-11T13:42:00Z"
}

Webhook callback

Когда batch готов, сервер вызывает ваш callback_url:

POST https://your-app.com/maxcheck-webhook
Headers:
  X-MaxCheck-Signature: <HMAC-SHA256>
Body:
  {
    "job_id": "job_8x4kpqz2nm",
    "status": "completed",
    "results_url": "https://api.checkmaxapp.com/v1/jobs/job_8x4kpqz2nm/results.csv",
    "stats": {
      "total": 10000,
      "registered": 7240,
      "not_found": 2760,
      "errors": 0
    }
  }

Подпись X-MaxCheck-Signature — HMAC-SHA256 от тела запроса с вашим секретом webhook. Обязательно проверяйте подпись, чтобы исключить подделку callback'а.

Без webhook (поллинг)

Если webhook поднять негде — поллинг статуса:

GET https://api.checkmaxapp.com/v1/jobs/job_8x4kpqz2nm

Возвращает текущий статус. Рекомендованный интервал поллинга — 30 секунд, чаще — 429.

Rate-limits

При превышении — 429 Too Many Requests + заголовок Retry-After в секундах. Простейшая реализация retry:

import time

def with_retry(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                wait = int(e.response.headers.get("Retry-After", 2 ** attempt))
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Exceeded retries")

Для production-нагрузок свяжитесь с поддержкой — лимиты повышаются индивидуально для проверенных клиентов.

Обработка ошибок

Все ошибки возвращаются с JSON-телом:

{
  "error": "invalid_phone_format",
  "message": "Phone must be in E.164 format",
  "request_id": "req_x9k2..."
}

request_id пригодится поддержке для разбора инцидентов — сохраняйте в логах.

Сравнение с green-api CheckAccount

Многие команды приходят с опытом green-api (WhatsApp CheckAccount). Принципиальные отличия:

Для российской аудитории и B2C-сегмента MaxCheck даёт больше полей для персонализации и работает без подписочной модели — выгоднее при нерегулярных нагрузках.

Best practices

1. Нормализуйте номера на своей стороне — отдавайте в API уже E.164, иначе 422
2. Используйте batch для >100 номеров — экономит rate-limits
3. Реализуйте webhook вместо поллинга — снижает нагрузку
4. Логируйте request_id — пригодится при разборе
5. Храните результаты в своей CRM — не делайте повторных проверок тех же номеров
6. Соблюдайте 152-ФЗ — см. юридический материал

Что дальше

• Тарифы и скидки
• Бесплатный trial 5 проверок
• Как очистить базу 100k
• REST API personal cabinet

Получить токен и протестировать API на 5 бесплатных проверках — прямо сейчас на checkmaxapp.com.