Phone Contact Rules

Per-phone-number allow/block rules for inbound calls and text messages. The phone number's filter_mode field decides how the rule list is interpreted:

• filter_mode: "whitelist" — only callers matching an allow rule can reach the number
• filter_mode: "blacklist" — every caller can reach the number except those matching a block rule

Set filter_mode on the phone number itself via PATCH /numbers/{phone_number_id} — see Phone numbers. Rules match on exact E.164 phone numbers only in v1 (match_type: "exact_number"); the field is wired in to stay forward-compatible when additional match types are added.

A rule with status: "paused" reserves the target slot without taking effect, so you can stage policy changes without losing the uniqueness claim.

Auth. List, get, and create accept admin API keys, claimed agent keys, and Clerk JWT; unclaimed (mid-signup) agent keys are rejected. PATCH, DELETE, and the org-wide list are admin + JWT only.

GET /numbers/{phone_number_id}/contact-rules

List contact rules for a phone number, newest first.

Path parameters

Query parameters

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

POST /numbers/{phone_number_id}/contact-rules

Create an allow or block rule on a phone number.

Path parameters

Request body

New rules always start with status: "active" — to pause a rule use Update contact rule.

Request example

JSON

Response (201)

Returns the created rule.

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /numbers/{phone_number_id}/contact-rules/{rule_id}

Fetch a single contact rule by ID.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

PATCH /numbers/{phone_number_id}/contact-rules/{rule_id}

Update a rule's action or status.

Auth: admin API key or Clerk JWT only.

match_type and match_target are immutable — delete the rule and create a new one to change the target.

Path parameters

Request body

At least one of:

Sending null for either field is a client error (422) — omit the field to leave it unchanged.

Code examples

cURL

cURL

JavaScript

Python

DELETE /numbers/{phone_number_id}/contact-rules/{rule_id}

Delete a contact rule. Returns 204 No Content on success.

Auth: admin API key or Clerk JWT only.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

GET /phone/contact-rules

Org-wide aggregate list of phone contact rules across every phone number the caller can see. Intended for admin dashboards that render rules org-wide without fanning out one per-number request per number.

Auth: admin API key or Clerk JWT only.

Results are ordered created_at descending, with id as a stable tiebreaker so pagination stays consistent when rules from different numbers share a microsecond.

Query parameters

Response (200)

Returns an array of contact rule objects — same shape as the per-number list.

Code examples

cURL

cURL

JavaScript

Python

• Filtering guide — narrative walk-through of whitelist/blacklist semantics across mail and phone
• Phone numbers — includes the filter_mode field that interprets these rules
• Mail contact rules — the mail-side equivalent