# LeadDeus Public API Documentation Base URL: `https://app.leaddeus.io` (all paths below are relative to it) API version: `v1` — all endpoints are prefixed with `/api/v1` The LeadDeus Public API lets you programmatically: - **Email databases**: upload CSV databases, list/inspect them, distribute them into email campaigns — as separate steps or as one combined operation. - **Phone databases**: upload CSV phone bases, append phones to an existing base, list/inspect them. - **Email campaigns**: start, pause, stop, delete. - **SMS campaigns**: list, start, cancel a schedule, delete. - **Event-triggered campaigns**: fire single template emails via webhook events. - **Analytics**: pull email/SMS statistics into your own systems (ETL, dashboards, AI agents). Everything the API does is visible in the regular web UI afterwards — the API uses exactly the same data and pipelines as the UI. --- ## 0. How LeadDeus works: databases vs campaigns (important concept) LeadDeus deliberately separates **databases** from **campaigns** — this is core product architecture, not an API quirk: - A **database** is a standalone, reusable pool of contacts (emails or phones) with metadata: countries, custom fields, validation results. Databases live on their own — they are NOT tied to any campaign. - A **campaign** is a sending configuration: sender account, template, limits. Campaigns do not "own" a database. - **Distribution** is the act of assigning contacts FROM a database INTO one or more campaigns. Within each country bucket, contacts are split **as evenly as possible (round-robin) across ALL selected campaigns**, so every campaign gets a similar country mix. You choose which countries/segments to distribute — the rest stays in the database for future use. If you are used to tools where you "upload a list directly into each campaign", note the difference: in LeadDeus you upload once into a database, then distribute — and re-distribute the same database later, into other campaigns or other segments, without re-uploading. Typical flows the API supports: 1. **Upload only** — put a database into your pool, distribute later (from the API or the UI). 2. **Distribute only** — assign contacts of an already-uploaded database to a new set of campaigns. 3. **Upload + distribute in one call** — the common automation case: the CSV is uploaded, parsed, and immediately distributed to the campaigns you chose. --- ## 1. Getting access (API key) API keys are issued manually by the LeadDeus team: 1. Contact your LeadDeus account manager (or support) and request an API key for your account. 2. An admin creates a key bound to **your user account** in the admin panel (`/admin/api-keys`). 3. You receive the raw key **once**. It looks like: `ld_9f2b...` (about 45 characters). Store it securely — it cannot be shown again, only revoked and re-issued. Key facts: - A key sees **only your account's data** (databases, campaigns, analytics). There is no way to access other users. - If a key is compromised, ask the admin to deactivate it — deactivation takes effect immediately. - All requests must be made over **HTTPS** with the key in the `Authorization` header: ``` Authorization: Bearer ld_YOUR_KEY_HERE ``` Quick connectivity check: ```bash curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ https://app.leaddeus.io/api/v1/me ``` ```json { "success": true, "key": { "id": 12, "name": "Client X — databases", "scope": "user", "user_id": 345 } } ``` ## 2. General conventions **Rate limit:** 100 requests per minute per key (429 when exceeded). **Responses:** JSON. Success responses contain `"success": true`. Errors always look like: ```json { "success": false, "error": "Human-readable message" } ``` **HTTP status codes:** | Code | Meaning | |---|---| | 200 | Success (read operations) | | 202 | Accepted — async work started (uploads, distribution, campaign start). Poll the progress endpoint. | | 400 | Validation error (bad parameters, campaign not ready, etc.) | | 401 | Missing or invalid API key | | 402 | Insufficient balance | | 403 | Key scope violation (e.g. a master key calling a user-scoped endpoint) | | 404 | Resource not found (or not owned by you) | | 409 | Conflict (e.g. database still being parsed) | | 429 | Rate limit exceeded | | 500 | Server error | **Asynchronous work:** uploads, parsing and distribution run in the background. Endpoints that start async work return `202` with identifiers you use for polling: - `run_id` — parse/ingest progress → `GET .../ingest-status/` - `task_id` — distribution/combined progress → `GET /api/v1/uploads//progress` Poll every 3–5 seconds until `status` becomes `done` / `completed` or `failed`. --- ## 3. Email databases Email databases go through two phases: **parsing** (CSV → validated recipients stored in your database pool) and **distribution** (recipients → leads assigned to campaigns). You can run them separately or combined. ### 3.1 Upload a database (without distribution) ``` POST /api/v1/email-databases Content-Type: multipart/form-data ``` | Field | Required | Description | |---|---|---| | `file` | yes | CSV file. Column names are auto-detected (Contact Detector V2) — no strict header names required. | | `name` | no | Display name (defaults to filename) | | `description` | no | Free-form description | | `email_column` | no | 0-based column index to force as the email column | | `country_column` | no | 0-based column index to force as the country column | ```bash curl -X POST -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ -F "file=@leads_de.csv" -F "name=DE leads March" \ https://app.leaddeus.io/api/v1/email-databases ``` ```json { "success": true, "database_id": 771, "run_id": "a1b2c3...", "name": "DE leads March", "status": "pending" } ``` Poll parsing progress: ```bash curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ https://app.leaddeus.io/api/v1/email-databases/ingest-status/a1b2c3... ``` ```json { "success": true, "status": "running", // queued | running | done | failed "database_id": 771, "total_rows": 52000, "rows_processed": 31000, "emails_valid": 29800, "emails_invalid": 1200, "no_country_emails": 400, "countries": {"DE": 29400} } ``` When `status` is `done`, the database is ready (`"status": "completed"` in the detail endpoint). ### 3.2 List and inspect databases ```bash curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" https://app.leaddeus.io/api/v1/email-databases curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" https://app.leaddeus.io/api/v1/email-databases/771 ``` The detail response includes `total_emails`, `no_country_emails`, `countries` (per-country counts), `custom_fields` (extra CSV columns available as template variables), `times_used`, `status`. ### 3.3 List your campaigns (for distribution) ```bash curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" https://app.leaddeus.io/api/v1/campaigns ``` ```json { "success": true, "campaigns": [ { "id": 101, "name": "DE Spring", "status": "active", "account_type": "gmail", "account_email": "sender1@gmail.com", "group": {"id": 3, "name": "DE", "color": "#22c55e"} } ] } ``` Only campaigns with a connected Gmail or SMTP account can receive leads. ### 3.4 Preview a distribution (optional, read-only) ``` POST /api/v1/email-databases//analyze-distribution Content-Type: application/json { "campaign_ids": [101, 102] } ``` Returns per-country counts plus a `distribution_preview` (leads per campaign per country). ### 3.5 Distribute an existing database into campaigns ``` POST /api/v1/email-databases//distribute Content-Type: application/json ``` ```json { "campaign_ids": [101, 102], "countries": ["DE", "AT"], "upload_mode": "append", "consent_confirmed": true } ``` | Field | Required | Description | |---|---|---| | `campaign_ids` | yes | Target campaigns (must be yours, with a connected email account) | | `countries` | no | Country buckets to distribute (ISO codes). Include `"no_country"` to also distribute recipients without a resolved country. If omitted: all countries **except** `no_country`. | | `upload_mode` | no | `"append"` (default) adds leads; `"replace"` deletes ALL existing leads in the target campaigns first | | `consent_confirmed` | yes | Must be `true` — you confirm you have the right to email these contacts | | `custom_fields_mapping` | no | Object `{source_column: target_name}` to rename/limit custom fields for this run only | **How distribution works:** within each country bucket, leads are split **evenly (round-robin) across ALL selected campaigns** — every campaign gets a similar country mix. Duplicates (same email already in a campaign) are skipped. ```json { "success": true, "task_id": "8e3f...", "message": "Distribution task started" } ``` Poll: ```bash curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ https://app.leaddeus.io/api/v1/uploads/8e3f.../progress ``` ```json { "success": true, "status": "processing", "phase": "distributing", "progress": "Uploading leads: 12,000/29,800", "current": 12000, "total": 29800 } ``` When `status` is `completed`, a `result` object is included with `total_uploaded`, `duplicates_skipped`, `results_by_country`, etc. ### 3.6 Upload AND distribute in one operation The most common flow: one request that uploads a CSV and, once parsing finishes, automatically distributes it into the selected campaigns. ``` POST /api/v1/email-databases/upload-and-distribute Content-Type: multipart/form-data ``` | Field | Required | Description | |---|---|---| | `file` | yes | CSV file | | `campaign_ids` | yes | JSON array string (`"[101,102]"`) or comma-separated (`"101,102"`) | | `consent_confirmed` | yes | `"true"` | | `countries` | no | JSON array string or comma-separated; may include `"no_country"` | | `upload_mode` | no | `"append"` (default) or `"replace"` | | `name`, `description` | no | Database metadata | | `custom_fields_mapping` | no | JSON object string | Campaign and consent validation happens **before** the file is accepted — configuration errors fail fast with 400. ```bash curl -X POST -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ -F "file=@leads_de.csv" \ -F "name=DE leads March" \ -F 'campaign_ids=[101,102]' \ -F "countries=DE,AT" \ -F "upload_mode=append" \ -F "consent_confirmed=true" \ https://app.leaddeus.io/api/v1/email-databases/upload-and-distribute ``` ```json { "success": true, "database_id": 772, "run_id": "c4d5...", "task_id": "f7g8...", "status": "pending" } ``` Poll `GET /api/v1/uploads//progress` — the `phase` field tells you where you are: - `"parsing"` — CSV is being validated and imported - `"distributing"` — leads are being assigned to campaigns Detailed parse counters are available via `GET /api/v1/email-databases/ingest-status/`. ### 3.7 Remove a specific email from your databases ``` POST /api/v1/email-databases/remove-email Content-Type: application/json ``` ```json { "email": "user@example.com" } ``` | Field | Required | Description | |---|---|---| | `email` | yes | Address to remove (case-insensitive) | | `database_id` | no | Limit removal to one database. Default: **all** your email databases | ```bash curl -X POST -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{"email":"user@example.com","database_id":771}' \ https://app.leaddeus.io/api/v1/email-databases/remove-email ``` The address is deleted from the stored recipients and the affected database counters are fixed (`total_emails`, `countries`, `no_country_emails`). Cleaned-CSV downloads and future distributions will no longer include it. Leads already created in campaigns are **not** affected. ```json { "success": true, "email": "user@example.com", "removed_total": 2, "databases": [ { "id": 771, "name": "DE leads March", "removed": 1 }, { "id": 780, "name": "EU pool", "removed": 1 } ] } ``` Returns `404` when the address is not found in the target database(s). This is the API counterpart of the "Remove Email Address" tool on the Email Databases page. --- ## 4. Phone databases Phone databases have **no distribution step** — SMS campaigns reference a database directly. **Important:** `POST /api/v1/phone-databases` **always creates a new database**. One HTTP request = one database. Do **not** call it once per visit, once per webhook, or every few minutes with 1–10 rows — you will get dozens of tiny databases instead of one pool. To catch this misuse early, the API refuses a **fragmenting upload**: if the CSV contains fewer than 10 rows **and** you created another database of the same name (timestamps like ` 16:27 UTC` and `(Copy)` suffixes are ignored when comparing) in the last 30 minutes, the request is rejected with `409` and the body includes the existing `database_id` so you can switch to `POST /api/v1/phone-databases//append`. Larger CSVs (10+ rows) always create a new database as usual. The same guard applies to `POST /api/v1/email-databases`. - Buffer phones on your side and upload **one CSV in one request** (preferred for a daily/hourly dump). - If numbers arrive one-by-one (webhooks, live visits), create the database **once**, save `database_id`, and send later rows to `POST /api/v1/phone-databases//append`. - Do not put a per-request timestamp in `name` (`Visits leads 16:27 UTC`). Use a stable name (`Visits leads 2026-09-11`). ### 4.1 Upload (creates a NEW database) ``` POST /api/v1/phone-databases Content-Type: multipart/form-data ``` ```bash curl -X POST -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ -F "file=@phones.csv" -F "name=Phones Q3" \ https://app.leaddeus.io/api/v1/phone-databases ``` CSV requirements: a phone column (`phone_number`, `phone`, `mobile`, `tel`, `telephone`) or any layout — the V2 parser auto-detects phone/country columns. Numbers are normalized and validated. ```json { "success": true, "database_id": 55, "run_id": "h9i0...", "status": "pending" } ``` Poll `GET /api/v1/phone-databases/ingest-status/` until `status` is `done`. Keep the returned `database_id` — you need it to append later. ### 4.2 Append phones to an existing database ``` POST /api/v1/phone-databases//append ``` Adds numbers to a database you already created. Duplicates (same E.164 already in this database) are skipped. Does **not** create a new database. **Storage:** JSON appends never touch object storage. CSV appends stream through storage only to hand the file to the ingest worker and the delta CSV is deleted after ingest — the database keeps exactly one file (`original.csv` from the initial upload), no per-append accumulation. **JSON (webhooks / one-by-one, up to 500 phones, synchronous):** ```bash curl -X POST -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{"phone":"+14155552671","first_name":"Ada"}' \ https://app.leaddeus.io/api/v1/phone-databases/55/append ``` Or a small batch: ```json { "phones": ["+14155552671", {"phone": "+14155552672", "first_name": "Ada"}] } ``` ```json { "success": true, "database_id": 55, "added": 1, "duplicates": 0, "invalid": 0, "total_phones": 33 } ``` **CSV (larger batches, asynchronous):** same multipart `file` as upload. Returns `202` with `run_id` — poll ingest-status. ```bash curl -X POST -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ -F "file=@more_phones.csv" \ https://app.leaddeus.io/api/v1/phone-databases/55/append ``` Typical live-visits flow: ``` 1. POST /api/v1/phone-databases → save database_id (once) 2. For each visit / webhook: POST /api/v1/phone-databases//append with {"phone": "..."} ``` ### 4.3 List and inspect ```bash curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" https://app.leaddeus.io/api/v1/phone-databases curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" https://app.leaddeus.io/api/v1/phone-databases/55 ``` Detail includes `total_phones`, `invalid_count`, `countries`, `csv_columns`, `variable_max_lengths`. ### 4.4 Remove a specific phone from your databases ``` POST /api/v1/phone-databases/remove-phone Content-Type: application/json ``` ```json { "phone": "+14155552671" } ``` | Field | Required | Description | |---|---|---| | `phone` | yes | Number to remove — any common format accepted, normalized to E.164 server-side | | `database_id` | no | Limit removal to one database. Default: **all** your phone databases | ```bash curl -X POST -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{"phone":"+14155552671"}' \ https://app.leaddeus.io/api/v1/phone-databases/remove-phone ``` The number is deleted from the stored recipients and the affected database counters are fixed (`total_phones`, `countries`). Campaigns load recipients at send time, so the number is automatically excluded from every not-yet-sent SMS and WhatsApp campaign using these databases. ```json { "success": true, "phone": "+14155552671", "removed_total": 1, "databases": [ { "id": 55, "name": "Phones Q3", "removed": 1 } ] } ``` Returns `404` when the number is not found in the target database(s). This is the API counterpart of the "Remove Phone Number" tool on the Phone Databases page. --- ## 5. Email campaigns (lifecycle) All four operations mirror the web UI exactly, including every validation. ### 5.1 Start ``` POST /api/v1/campaigns//start ``` Validates: email account connected & active, template exists, pending leads exist, email balance covers at least one email. Sets the campaign to `active`; sending begins within ~60 seconds (batch processor). - Resuming from `paused`: all counters are preserved. - Starting from `stopped`: statistics reset, a new sending cycle begins. ```json { "success": true, "message": "Campaign started! Sending 29800 emails...", "pending_leads": 29800 } ``` ### 5.2 Pause ``` POST /api/v1/campaigns//pause ``` Temporary pause — warmup progress and lead statuses are fully preserved. Resume with `/start`. ### 5.3 Stop ``` POST /api/v1/campaigns//stop ``` Full reset: all `sent`/`failed`/`sending` leads return to `pending`, warmup resets to day 0, daily counters reset. Starting again begins a completely new cycle. ```json { "success": true, "message": "Campaign stopped and fully reset", "reset_leads": 15400, "warmup_reset": true } ``` ### 5.4 Delete ``` DELETE /api/v1/campaigns/ ``` **Irreversible.** Deletes all campaign leads (in batches), then the campaign with its templates and statistics. ```json { "success": true, "deleted_leads": 29800 } ``` --- ## 6. SMS campaigns SMS campaigns cannot be paused or stopped once sending — plan accordingly. A **scheduled** campaign can always be cancelled (funds are refunded). ### 6.0 Moderation (admin approval) Every SMS campaign passes **manual admin moderation** before it can be started. Moderation is a human process — there is no automatic approval and no fixed SLA; the admin is notified about new pending campaigns. The moderation state is fully visible via the API: | Field | Meaning | |---|---| | `moderation_status` | `pending` (awaiting review) / `approved` / `rejected` | | `moderation_note` | Admin's comment — for `rejected`, the reason and what to fix | | `moderated_at` | When the decision was made | Typical flow (fully via the API): ``` 1. POST /api/v1/phone-databases → upload the phone base 2. (opt.) POST /api/v1/sms-campaigns/estimate → cost preview before creating 3. POST /api/v1/sms-campaigns → create (moderation: pending) 4. Poll GET /api/v1/sms-campaigns/ every 5–15 min 5. approved → POST /api/v1/sms-campaigns//start rejected → read moderation_note, fix the campaign, resubmit (UI) ``` Starting a non-approved campaign is rejected with `400 "Campaign must be approved before sending"`. ### 6.1 Create / estimate ``` POST /api/v1/sms-campaigns Content-Type: application/json ``` ```json { "name": "September promo", "database_id": 55, "message_template": "Hi {{first_name}}, grab your offer: ...", "sender_id": "Acme", "target_countries": ["DE", "PL"] } ``` `201` → `{ "success": true, "campaign_id": 88, "status": "draft", "moderation_status": "pending" }`. The admin moderation team is notified automatically (same as UI creation). Options: A/B testing via `"is_ab_test": true` + `"variants": [{"variant_name": "A", "message_text": "..."}, {"variant_name": "B", ...}]` (2–4 variants, allocation is split evenly); `include_campaign_link_param: true`. Message texts pass the same forbidden-words filter as the UI. Cost preview without creating anything: ```bash curl -X POST -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{"database_id": 55, "message_template": "Hi {{first_name}}!", "target_countries": ["DE"]}' \ https://app.leaddeus.io/api/v1/sms-campaigns/estimate ``` Returns `total_cost_eur`, `total_recipients`, `estimated_parts`, `country_breakdown` — and routing errors (e.g. mixing countries from incompatible pipelines) before you create anything. ### 6.2 List & detail ```bash curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" https://app.leaddeus.io/api/v1/sms-campaigns curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" https://app.leaddeus.io/api/v1/sms-campaigns/ ``` Both return `status` (technical state), `moderation_status`, `moderation_note`, `moderated_at`, `sent_count`, `failed_count`, costs and `reserved_balance_eur`. ### 6.3 Start ``` POST /api/v1/sms-campaigns//start ``` Validations (same as the UI): the attached database is fully parsed, campaign status is `draft`/`failed`, moderation is `approved`, routing rules pass, balance covers the full cost. The full cost is **reserved (deducted) immediately**; unused portions are refunded automatically for failed messages. ```json { "success": true, "task_id": "sms-task-...", "reserved_eur": 412.50, "message": "Campaign queued for sending" } ``` ### 6.4 Cancel a scheduled campaign ``` POST /api/v1/sms-campaigns//cancel-schedule ``` Only for campaigns in `scheduled` status. Revokes the scheduled task, refunds the reserved funds, returns the campaign to `draft`. ```json { "success": true, "message": "Schedule cancelled and funds refunded", "refunded_amount_eur": 412.50 } ``` ### 6.5 Delete ``` DELETE /api/v1/sms-campaigns/ ``` Blocked while `sending`/`queued`; a `scheduled` campaign must be cancelled first (so its funds are refunded). Deletion runs in the background — the campaign shows `deleting` until done. ```json { "success": true, "message": "Campaign deletion started" } ``` --- ## 7. Event-triggered email campaigns (webhooks) Event-triggered campaigns send **one email to one lead** when an external system (your website, CRM, shop) fires a webhook event — e.g. "user registered", "deposit made". They have no databases, no schedule, no start/pause/stop lifecycle: the only controls are **activate/deactivate** and **delete**. Key properties: - The **email must already exist in your LeadDeus data** (one of your email databases or campaign leads). Unknown emails are rejected with `422` and recorded in the journal. - Template variables (`{{first_name}}`, `{{company}}`, …) are filled **from the stored record** in LeadDeus. Event-specific data (e.g. an amount) can be passed in the webhook's `extra_fields` and merged over the stored fields. - Each campaign exposes one or more **named triggers** (e.g. `registered`, `paid`), each with its own token and dedup window. The journal shows which trigger fired each send. - Trigger campaigns **never appear in distribution pickers** and cannot receive distributed leads. ### 7.1 Create a trigger campaign You can create it in the UI (Trigger Campaigns page) or via the API: ``` POST /api/v1/trigger-campaigns Content-Type: application/json ``` ```json { "name": "Registrations — Welcome", "account_type": "gmail", "gmail_account_id": 12, "subject": "Welcome, {{first_name}}!", "html_body": "

Hello {{first_name}}, thanks for registering!

", "triggers": [ { "name": "registered", "dedup_window_minutes": 10 }, { "name": "paid", "dedup_window_minutes": 0 } ] } ``` `201` → `{ "success": true, "campaign": { ..., "triggers": [{ "name": "registered", "token": "abc...", ... }] } }`. Save the tokens — your developer needs them for the webhook calls. ### 7.2 Fire a webhook event ``` POST /api/v1/triggers/fire Content-Type: application/json ``` ```json { "token": "abc...", "email": "lead@example.com", "extra_fields": { "plan": "pro", "amount": "100" } } ``` | Response | Meaning | |---|---| | `202 { "lead_id", "lead_uuid", "link_token", "status": "queued" }` | Email queued for immediate sending | | `200 { "deduplicated": true, "lead_id", "lead_uuid", "link_token" }` | Same trigger+email already fired within the dedup window — skipped | | `404` | Unknown trigger token | | `409` | Campaign (or this trigger) is deactivated — the attempt is journaled | | `422` | Email not found in your data — nothing sent, the attempt is journaled | Alternative to `token`: pass `"campaign_id": 123, "trigger_key": "registered"`. **Auto-create unknown contacts:** if the campaign was created with `"allow_auto_create": true`, you may pass `"create_if_missing": true` in the fire payload — an unknown email is then added to the campaign's technical `Trigger inbox — campaign ` database (fields from `extra_fields`) and the email is sent as usual. The `202` response includes `"created_contact": true`. Without the campaign flag, `create_if_missing` is refused with 422. **Add a single contact without CSV:** ``` POST /api/v1/email-databases//recipients { "email": "lead@example.com", "first_name": "Ada", "country": "DE", "custom_fields": {"plan": "pro"} } ``` Returns `201 { "created": true, ... }`; an email already present in that database returns `200 { "created": false, "reason": "duplicate" }` (idempotent retries are safe). **Matching keys for your CRM:** `lead_uuid` is the immutable public ID of the lead row; `link_token` is the recipient's stable identity keyed by `(email, your user)` — independent of CSV columns and campaigns, and the same token that appears in tracked links (`https://{custom-domain}/{slug}/{link_token}`). Both are also returned on deduplicated `200` responses and shown in the journal. **Identity is per-channel by design.** The email `link_token` and the SMS `token` are two independent identities: one keyed by `(email, user)`, the other by `(phone, user)`. A person with both an email and a phone therefore has **two different tokens** — LeadDeus does not merge them into a single cross-channel ID. If you need to know that an email-clicker and an SMS-clicker are the same person, match on **your own user ID**: pass it in `extra_fields` (or as a CSV column) and join on your side. ### 7.3 Manage trigger campaigns ```bash GET /api/v1/trigger-campaigns # list with sent/failed counters GET /api/v1/trigger-campaigns/ # detail + webhook setup + available_variables POST /api/v1/trigger-campaigns//activate # resume firing POST /api/v1/trigger-campaigns//deactivate # pause firing (reversible) PUT /api/v1/trigger-campaigns//template # update {subject, html_body} GET /api/v1/trigger-campaigns//journal # send journal ``` Journal filters: `?status=sent|failed`, `?trigger=registered`, `?email=foo`, `limit`, `offset`. Each entry shows the email, the trigger name, final status (`sent`/`failed`), error message, the data used, and timestamps. Deleting a trigger campaign uses the regular `DELETE /api/v1/campaigns/`. --- ## 8. Analytics API Read-only statistics endpoints for ETL/dashboards. All accept `start_date` / `end_date` query params (`YYYY-MM-DD`, Europe/Warsaw calendar days, max range 366 days) and support pagination via `limit` / `offset`. | Endpoint | Description | |---|---| | `GET /api/v1/analytics/campaigns` | List email & SMS campaigns (id/name/status) for filter discovery | | `GET /api/v1/analytics/email/summary` | Sends/bounces totals + daily breakdown | | `GET /api/v1/analytics/email/campaigns` | Per-campaign sends, bounces, total/unique clicks | | `GET /api/v1/analytics/email/clickers` | Unique email clickers with counts, countries, devices — each row includes `link_token` (the recipient's stable identity, same as in trigger `fire`/`journal`) | | `GET /api/v1/analytics/email/links` | Click analytics grouped by routing link | | `GET /api/v1/analytics/email/export` | CSV export of email statistics | | `GET /api/v1/analytics/sms/campaigns` | Per-campaign SMS delivery & click stats | | `GET /api/v1/analytics/sms/clicks` | SMS click events — each row includes `token` (the phone's stable sms identity, e.g. `gold9238`; a different value space from the email `link_token`) | | `GET /api/v1/analytics/sms/links` | SMS clicks grouped by routing link | | `GET /api/v1/analytics/sms/stats` | SMS totals for a period | | `GET /api/v1/analytics/sms/export-clickers` | CSV export of SMS clickers | Common optional filters: `campaign_id`, `bot_filter=all|real|bot` (click endpoints), `quality=1` (quality SMS clicks only: real user, unique, mobile), `channel=sms|whatsapp` where applicable. Example: ```bash curl -H "Authorization: Bearer ld_YOUR_KEY_HERE" \ "https://app.leaddeus.io/api/v1/analytics/email/summary?start_date=2026-08-01&end_date=2026-08-31" ``` ```json { "success": true, "period": {"start": "2026-08-01", "end": "2026-08-31"}, "totals": {"sent": 182300, "bounced": 2100, "total": 184400}, "daily": [{"date": "2026-08-01", "sent": 5900, "bounced": 80, "total": 5980}] } ``` --- ## 9. Typical integration scenarios ### Scenario A: nightly sync of a fresh email base into 3 campaigns ``` 1. POST /api/v1/email-databases/upload-and-distribute (file + campaign_ids=[101,102,103] + consent_confirmed=true) 2. Poll GET /api/v1/uploads//progress every 5 s → phase parsing → distributing → status completed 3. POST /api/v1/campaigns//start (for each campaign, or use your UI schedule) ``` ### Scenario B: reuse the same master base across different campaign sets ``` 1. POST /api/v1/email-databases → database_id (once) 2. For each new campaign set: POST /api/v1/email-databases//distribute with different campaign_ids / countries ``` ### Scenario C: upload a phone base and start an approved SMS campaign ``` 1. POST /api/v1/phone-databases → database_id 2. Poll GET /api/v1/phone-databases/ingest-status/ → done 3. (Create/configure the SMS campaign — UI or your existing flow; moderation approval is required before any start) 4. POST /api/v1/sms-campaigns//start ``` ### Scenario D: stream visit phones into one database (webhooks) ``` 1. Once: POST /api/v1/phone-databases (even a 1-row CSV) → save database_id 2. On each visit: POST /api/v1/phone-databases//append body: {"phone": "+1...", "first_name": "..."} Do NOT call POST /api/v1/phone-databases again — that creates a new database. ``` ## 10. Notes & limits - **Idempotency:** `POST /api/v1/phone-databases` and `POST /api/v1/email-databases` always create a NEW database. Retrying that upload POST creates a duplicate — track the returned `database_id`. To add more phones to an existing base, use `POST /api/v1/phone-databases//append` (duplicates of phones already in that database are skipped). - **Fragmentation guard:** a tiny upload (< 10 rows) that reuses the name of a database you created in the last 30 minutes is rejected with `409` and `existing_database_id` in the body — use append instead of creating another fragment. - **Distribution quotas:** there are no per-campaign lead quotas at distribution time. Sending limits (daily limits, warmup) apply later, at send time. - **`replace` mode deletes ALL existing leads** in the target campaigns before inserting new ones — use with care. - **File size:** the same limits apply as in the web UI. For very large files (100+ MB), expect parsing to take several minutes; keep polling. - **Timestamps** in responses are ISO 8601; `scheduled_at`-style fields are UTC (suffixed `Z`). - WhatsApp campaigns are **not** manageable via the API (they are launched through admin moderation). - Event-triggered campaigns have no start/pause/stop and no distribution — only activate/deactivate/delete.