Import numbers into the suppression list

Format. numbers is a JSON array of strings, 1 to 200,000 entries, each 5 to 32 characters. An entry outside that length fails the whole request with 400. Each entry has spaces, non-breaking spaces, dashes, dots and parentheses stripped, and must then be E.164 (+ followed by 2 to 15 digits). Entries that are not are skipped and counted in rejected, with up to 10 shown in rejectedSample. Local-format numbers such as 3001234567 are not given a country code; fix the file first. Duplicates in the request are collapsed.

Size. Request bodies are limited to 1 MB, roughly 50,000 to 60,000 numbers. Split larger registries across several requests. The import is one-way: numbers already on the list keep their original reason, source and date.

Side effects. Inserts suppression rows in batches of 1,000. Those numbers immediately become uncontactable on every channel. Writes an audit entry (import_suppressions) with the source and counts, never the numbers.

Idempotency. Safe to retry, including with the same file. Existing numbers are left unchanged, and the response counts them as suppressed again.

Access

Required scope: full. Signed-in users need the owner or admin role.
Rate limit: General API — 120 (Starter), 200 (Growth), 300 (Business) or 600 (Enterprise) requests/min per workspace. See Rate limits.
Plan: Available on every plan.

Loads a national do-not-call registry export or your own opt-out list into the workspace suppression list. Every outbound call, WhatsApp send and campaign email checks this list first, whatever the country config says. None of the registries offers a per-number lookup API, so importing the file is how you meet the duty to consult them. The main one is Colombia's Registro de Números Excluidos under Ley 2300 de 2023. **Format.** `numbers` is a JSON array of strings, 1 to 200,000 entries, each 5 to 32 characters. An entry outside that length fails the **whole request** with 400. Each entry has spaces, non-breaking spaces, dashes, dots and parentheses stripped, and must then be E.164 (`+` followed by 2 to 15 digits). Entries that are not are skipped and counted in `rejected`, with up to 10 shown in `rejectedSample`. Local-format numbers such as `3001234567` are **not** given a country code; fix the file first. Duplicates in the request are collapsed. **Size.** Request bodies are limited to 1 MB, roughly 50,000 to 60,000 numbers. Split larger registries across several requests. The import is one-way: numbers already on the list keep their original reason, source and date. **Side effects.** Inserts suppression rows in batches of 1,000. Those numbers immediately become uncontactable on every channel. Writes an audit entry (`import_suppressions`) with the source and counts, never the numbers. **Idempotency.** Safe to retry, including with the same file. Existing numbers are left unchanged, and the response counts them as `suppressed` again. **Access** - **Required scope:** `full`. Signed-in users need the `owner` or `admin` role. - **Rate limit:** General API — 120 (Starter), 200 (Growth), 300 (Business) or 600 (Enterprise) requests/min per workspace. See [Rate limits](/rate-limits). - **Plan:** Available on every plan.

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).

Request

This endpoint expects an object.

numberslist of stringsRequired

Phone numbers to suppress. Formatting characters are stripped. Each must then be E.164.

sourceenumRequired

Where the list came from. It is stored on every new row and drives the stale report.

registry:rne_co: Colombia, Registro de Números Excluidos (CRC), Ley 2300 de 2023.
registry:dnc_us: United States National Do Not Call Registry. The scrub must be under 31 days old.
registry:repep_mx: Mexico, Registro Público para Evitar Publicidad (Profeco).
registry:nmp_br: Brazil, Não Me Perturbe.
customer_list: your own opt-out list. It is never reported as stale.

Where the list came from. It is stored on every new row and drives the `stale` report. - `registry:rne_co`: Colombia, Registro de Números Excluidos (CRC), Ley 2300 de 2023. - `registry:dnc_us`: United States National Do Not Call Registry. The scrub must be under 31 days old. - `registry:repep_mx`: Mexico, Registro Público para Evitar Publicidad (Profeco). - `registry:nmp_br`: Brazil, Não Me Perturbe. - `customer_list`: your own opt-out list. It is never reported as stale.

Allowed values:

reasonstringOptional<=200 characters

Free-text note stored on each new row. It defaults to imported:<source> when omitted or blank.

Response

Import result.

dataobject

Counts from one suppression import.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error

Idempotency. Safe to retry, including with the same file. Existing numbers are left unchanged, and the response counts them as suppressed again.

Access

Required scope: full. Signed-in users need the owner or admin role.
Rate limit: General API — 120 (Starter), 200 (Growth), 300 (Business) or 600 (Enterprise) requests/min per workspace. See Rate limits.
Plan: Available on every plan.