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:

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. Prior opt-in, when your workspace turned require_opt_in on for that country and contactId is given. Enforced since 2026-09-15: the contact needs a live granted voice_call consent record (no expires_at, or one still in the future) or the call is refused with code: no_opt_in. It is read from YOUR saved config only — the published country defaults say require_opt_in: true for CO and BR, and those describe the law, not what the gate enforces. A country you never configured, or one still carrying the column’s false default, is not enforced. A call with no contactId is allowed through and logged: the consent ledger is keyed by contact, so that is a question with no answer rather than a negative one.
7. Daily attempt limit, when contactId is given. Counts the contact’s call rows since local midnight.
8. Total attempt limit, when contactId is given. Uses the contact’s call_attempts counter.

In a campaign, no_opt_in marks the contact invalid — not dnc (nobody opted out; granting consent later must make the row dialable again) and not failed (no call was attempted, and failed feeds the failure KPIs and the retry budget). The campaign keeps running through the rest of its contacts.

To test consent on its own, 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.