Документация API приёма заявок

POST /api/v1/leads

Создание заявки

Ключ определяет сайт и организацию. Content-Type должен быть application/json, общий размер запроса — не более 64 KB.

cURL

curl --request POST \
  --url https://api.leadpending.com/api/v1/leads \
  --header "Authorization: Bearer lp_live_<secret>" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: contact_018f47f2" \
  --data '{
    "external_id": "contact-form-018f47f2",
    "name": "Jane Doe",
    "email": "[email protected]",
    "company": "Example Inc",
    "subject": "SEO audit",
    "message": "Can you help us with three websites?",
    "page_url": "https://example.org/pricing",
    "locale": "en",
    "metadata": { "utm_source": "google" }
  }'

Поля

Поле	Тип	Правило	Описание
email	string	Обязательно	Email лида.
message	string	Обязательно	Текст заявки до 20 000 символов.
external_id	string	Опционально	Стабильный ID, уникальный внутри сайта.
name · phone · company	string	Опционально	Контактные данные для оператора.
subject	string	Опционально	По умолчанию «Inquiry from {site name}».
page_url	URL	Опционально	Страница, с которой отправлена форма.
locale	string	Опционально	Язык ответа, например en или ru.
metadata	object	Опционально	Дополнительный JSON: UTM, бюджет и т. п., до 20 KB.

Сделайте retry формы безопасным

Передавайте стабильный Idempotency-Key для одной отправки формы. Повтор того же ключа и payload вернёт исходную заявку с 200. Тот же ключ с другими данными вернёт 409.

Ответы

Статус 201 означает новую заявку. Идемпотентный повтор с тем же Idempotency-Key или external_id возвращает тот же ресурс со статусом 200.

201 Created

HTTP/1.1 201 Created
Content-Type: application/json

{
  "data": {
    "id": "0198…",
    "status": "pending",
    "created_at": "2026-08-02T12:00:00Z"
  }
}

Контракт ошибок

HTTP	Код	Действие
400	VALIDATION_FAILED	Поле, размер payload или JSON некорректны.
401	INVALID_API_KEY	Ключ отсутствует, отозван или относится к неактивному сайту.
409	IDEMPOTENCY_CONFLICT	Ключ идемпотентности уже использован с другим payload.
429	RATE_LIMITED	Превышен настроенный rate limit ключа.
503	SERVICE_UNAVAILABLE	Приём временно недоступен; повторите запрос с тем же ключом.

Серверный route Next.js

До этого вызова проверьте поля и Turnstile. Возвращайте браузеру успех только после 200 или 201 от LeadPending.

app/api/contact/route.ts

import { NextResponse } from 'next/server'

export async function POST(request: Request) {
  const form = await request.json()

  // Validate fields and Turnstile here first.
  const response = await fetch(
    'https://api.leadpending.com/api/v1/leads',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.LEADPENDING_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': form.submissionId,
      },
      body: JSON.stringify({
        external_id: form.submissionId,
        name: form.name,
        email: form.email,
        message: form.message,
        page_url: form.pageUrl,
      }),
    },
  )

  const payload = await response.json()
  if (response.status !== 200 && response.status !== 201) {
    return NextResponse.json(
      { error: payload?.error?.code ?? 'LEAD_NOT_ACCEPTED' },
      { status: response.status },
    )
  }

  return NextResponse.json({ accepted: true })
}

Production checklist

01Храните LEADPENDING_API_KEY как серверный secret.
02Создавайте один стабильный ключ идемпотентности на отправку формы.
03Логируйте status и error code без email и message.
04Считайте принятыми только ответы 200 и 201.
05Отправьте тестовую заявку до переключения production-формы.