Check whether a number may be contacted now

Runs the same gate that every outbound call, WhatsApp send and campaign email passes before it leaves, and reports whether contacting phoneNumber is allowed right now and, if not, why. Nothing is dialed or sent.

The country comes from the number’s prefix: +57 CO, +52 MX, +55 BR, +1 US (this includes Canada and the Caribbean), +54 AR, +56 CL, +51 PE. Any other prefix uses a generic default: 08:00–20:00, 3 attempts per day, 10 in total, DNC check on. The effective rules are the workspace’s saved config for that country, or the country defaults. Checks run in this order, and the first failure is returned:

Allowed call hours. When the workspace has a time zone in its settings, that time zone replaces the country’s. The generic default uses America/Bogota when no time zone is set. The end time is exclusive.
Blocked prefixes.
Suppression list. Exact E.164 match, checked whatever require_dnc_check says.
The contact’s DNC status, when contactId is given.
DNC by phone number. Any contact in the workspace with this phone or WhatsApp number marked do-not-call. Runs only when require_dnc_check is on.
Daily attempt limit, when contactId is given. Counts the contact’s call rows since local midnight.
Total attempt limit, when contactId is given. Uses the contact’s call_attempts counter.

Consent records are not part of this check. require_opt_in is stored on configs but is not enforced here. To test consent, use GET /api/compliance/consent/check/{contactId}/{consentType}.

The answer is only valid for the moment it is computed. Hours and attempt counts change, so the real send re-checks.

Side effects. None. This is a read, but it is a POST, so API keys need write.

Idempotency. Safe to retry. The answer can change over time, as described above.

Access

Required scope: write. Any signed-in workspace 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.

Runs the same gate that every outbound call, WhatsApp send and campaign email passes before it leaves, and reports whether contacting `phoneNumber` is allowed **right now** and, if not, why. Nothing is dialed or sent. The country comes from the number's prefix: `+57` CO, `+52` MX, `+55` BR, `+1` US (this includes Canada and the Caribbean), `+54` AR, `+56` CL, `+51` PE. Any other prefix uses a generic default: 08:00–20:00, 3 attempts per day, 10 in total, DNC check on. The effective rules are the workspace's saved config for that country, or the country defaults. Checks run in this order, and the first failure is returned: 1. **Allowed call hours.** When the workspace has a time zone in its settings, that time zone replaces the country's. The generic default uses `America/Bogota` when no time zone is set. The end time is exclusive. 2. **Blocked prefixes.** 3. **Suppression list.** Exact E.164 match, checked whatever `require_dnc_check` says. 4. **The contact's DNC status**, when `contactId` is given. 5. **DNC by phone number.** Any contact in the workspace with this phone or WhatsApp number marked do-not-call. Runs only when `require_dnc_check` is on. 6. **Daily attempt limit**, when `contactId` is given. Counts the contact's call rows since local midnight. 7. **Total attempt limit**, when `contactId` is given. Uses the contact's `call_attempts` counter. Consent records are not part of this check. `require_opt_in` is stored on configs but is not enforced here. To test consent, use `GET /api/compliance/consent/check/{contactId}/{consentType}`. The answer is only valid for the moment it is computed. Hours and attempt counts change, so the real send re-checks. **Side effects.** None. This is a read, but it is a POST, so API keys need `write`. **Idempotency.** Safe to retry. The answer can change over time, as described above. **Access** - **Required scope:** `write`. Any signed-in workspace 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.

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

The number to check, in E.164 format with no spaces or dashes. It decides the country and is matched against the suppression list and DNC contacts.

contactIdstringOptionalformat: "uuid"

The contact being reached. Enables the contact DNC check and both attempt-limit checks.

Response

Whether contact is allowed and, if not, why.

dataobject

The outcome of the outbound compliance gate.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

Allowed call hours. When the workspace has a time zone in its settings, that time zone replaces the country’s. The generic default uses America/Bogota when no time zone is set. The end time is exclusive.
Blocked prefixes.
Suppression list. Exact E.164 match, checked whatever require_dnc_check says.
The contact’s DNC status, when contactId is given.
DNC by phone number. Any contact in the workspace with this phone or WhatsApp number marked do-not-call. Runs only when require_dnc_check is on.
Daily attempt limit, when contactId is given. Counts the contact’s call rows since local midnight.
Total attempt limit, when contactId is given. Uses the contact’s call_attempts counter.