Jelliu API documentation

curl -X POST https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "phoneNumber": "+573001234567",
  "email": "maria.gomez@example.com",
  "name": "María Gómez",
  "metadata": {
    "ciudad": "Medellín",
    "plan": "prepago",
    "saldo_pendiente": "45900"
  }
}'

{
  "data": {
    "id": "3f2e1d0c-9b8a-4776-8554-433221100fed",
    "tenant_id": "0e9d7c3b-8a1f-4c55-b7a2-3c4d5e6f7a8b",
    "campaign_id": "5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10",
    "phone_number": "+573001234567",
    "email": "maria.gomez@example.com",
    "whatsapp_number": null,
    "name": "María Gómez",
    "status": "pending",
    "metadata": {
      "ciudad": "Medellín",
      "plan": "prepago",
      "saldo_pendiente": "45900"
    },
    "call_attempts": 0,
    "last_called_at": null,
    "crm_external_id": null,
    "crm_provider": null,
    "sync_status": "none",
    "last_synced_to_crm_at": null,
    "sync_error": null,
    "opted_out_at": null,
    "opted_out_reason": null,
    "created_at": "2026-09-15T10:11:12.000Z",
    "updated_at": "2026-09-15T10:11:12.000Z",
    "deleted_at": null
  }
}

Adds one contact to a campaign that is not completed/archived. It is created pending. At least one of phoneNumber, email or whatsappNumber is required. For more than a handful of contacts use POST /api/campaigns/{campaignId}/contacts/bulk.

Deduplication. The contact is keyed by phone number inside the campaign:

The phone already exists in this campaign: the existing row is returned (still 201). Blank email, whatsapp_number and name are filled in from the request, and values already stored are never overwritten.
The contact was removed from this campaign earlier: it is restored as pending with the new values.
Email-only request (no phone or WhatsApp) whose address already belongs to a contact anywhere in the workspace (case-insensitive): that contact is returned, with a blank name filled in. Its campaign_id can then be a different campaign.

Adding a contact to an active campaign does not queue it. Pause and activate the campaign to reach it. A voice campaign can only call contacts with a real phone number; email-only contacts end as invalid there.

Side effects. Inserts the contact, records its consent provenance (api:manual, no evidence) and writes an audit entry. Nobody is contacted.

Idempotency. Safe to retry: the same phone (or the same address, for email-only contacts) returns the same row.

Webhook events. audit.log_recorded for webhooks subscribed to it. See Webhooks.

Access

Required scope: write (or full).
Rate limit: Contacts import — 5 requests/min per workspace, shared by every route under /api/campaigns/{campaignId}/contacts, on top of the general API limit. See Rate limits.
Plan: Counts against the workspace-wide contact cap (Starter 500, Growth 2,000, Business 20,000). Refused with 403 BILLING_ERROR when the cap is reached, even if the contact already exists.

Adds one contact to a campaign that is not `completed`/`archived`. It is created `pending`. At least one of `phoneNumber`, `email` or `whatsappNumber` is required. For more than a handful of contacts use `POST /api/campaigns/{campaignId}/contacts/bulk`. **Deduplication.** The contact is keyed by phone number inside the campaign: - The phone already exists in this campaign: the existing row is returned (still 201). Blank `email`, `whatsapp_number` and `name` are filled in from the request, and values already stored are never overwritten. - The contact was removed from this campaign earlier: it is restored as `pending` with the new values. - Email-only request (no phone or WhatsApp) whose address already belongs to a contact anywhere in the workspace (case-insensitive): that contact is returned, with a blank `name` filled in. Its `campaign_id` can then be a different campaign. Adding a contact to an `active` campaign does not queue it. Pause and activate the campaign to reach it. A voice campaign can only call contacts with a real phone number; email-only contacts end as `invalid` there. **Side effects.** Inserts the contact, records its consent provenance (`api:manual`, no evidence) and writes an audit entry. Nobody is contacted. **Idempotency.** Safe to retry: the same phone (or the same address, for email-only contacts) returns the same row. **Webhook events.** `audit.log_recorded` for webhooks subscribed to it. See [Webhooks](/webhooks). **Access** - **Required scope:** `write` (or `full`). - **Rate limit:** Contacts import — 5 requests/min per workspace, shared by every route under `/api/campaigns/{campaignId}/contacts`, on top of the general API limit. See [Rate limits](/rate-limits). - **Plan:** Counts against the workspace-wide contact cap (Starter 500, Growth 2,000, Business 20,000). Refused with 403 `BILLING_ERROR` when the cap is reached, even if the contact already exists.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication).

Path parameters

campaignIdstringRequiredformat: "uuid"

UUID of the campaign that receives the contact. An unknown, deleted or foreign campaign answers 404; a value that is not a UUID answers 400.

Request

This endpoint expects an object.

phoneNumberstringOptionalformat: "^\+[1-9]\d{1,14}$"

E.164 phone number with country code (Must be E.164 format). It is the dedup key in the campaign. Numbers shorter than 7 digits pass here but cannot be dialed and end as invalid.

emailstringOptionalformat: "email"<=320 characters

Email address (Invalid email). Required for email campaigns.

whatsappNumberstringOptionalformat: "^\+[1-9]\d{1,14}$"

E.164 WhatsApp number. Used as the dedup key when there is no phoneNumber.

namestringOptional<=200 characters

Contact’s name; the first word feeds contact.first_name.

metadatamap from strings to stringsOptional

Up to 20 keys matching ^[a-zA-Z0-9_-]+\$, string values up to 500 characters. The agent can read them, and tokens can use them as contact.metadata.<key>. Card-like and 9-digit ID-like numbers are redacted before storage.

crmExternalIdstringOptional<=500 characters

Id of the matching record in an external CRM.

crmProviderstringOptional<=50 characters

CRM the external id belongs to.

Response

The created, restored or existing contact.

dataobject

A contact row as returned by POST /api/campaigns/{campaignId}/contacts. Keys are snake_case. phone_number is always present: contacts saved with only a WhatsApp number use it, and email-only contacts get a synthetic key em:<16 hex>.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

Deduplication. The contact is keyed by phone number inside the campaign:

The phone already exists in this campaign: the existing row is returned (still 201). Blank email, whatsapp_number and name are filled in from the request, and values already stored are never overwritten.
The contact was removed from this campaign earlier: it is restored as pending with the new values.
Email-only request (no phone or WhatsApp) whose address already belongs to a contact anywhere in the workspace (case-insensitive): that contact is returned, with a blank name filled in. Its campaign_id can then be a different campaign.

Side effects. Inserts the contact, records its consent provenance (api:manual, no evidence) and writes an audit entry. Nobody is contacted.

Idempotency. Safe to retry: the same phone (or the same address, for email-only contacts) returns the same row.

Webhook events. audit.log_recorded for webhooks subscribed to it. See Webhooks.

Access

Required scope: write (or full).
Rate limit: Contacts import — 5 requests/min per workspace, shared by every route under /api/campaigns/{campaignId}/contacts, on top of the general API limit. See Rate limits.
Plan: Counts against the workspace-wide contact cap (Starter 500, Growth 2,000, Business 20,000). Refused with 403 BILLING_ERROR when the cap is reached, even if the contact already exists.