Phone Contact Rules

Per-identity allow/block rules for inbound calls and text messages. Rules attach to the agent identity itself and are addressed by agent_handle, covering both voice and SMS on the identity's phone number. The identity's phone_filter_mode field decides how the rule list is interpreted:

• phone_filter_mode: "whitelist" — only callers and senders matching an allow rule can reach the agent
• phone_filter_mode: "blacklist" — every caller and sender can reach the agent except those matching a block rule

Set phone_filter_mode on the identity via PATCH /identities/{agent_handle} — see Manage identities. 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" has no effect, but still counts as the rule for its number. Creating a duplicate returns 409.

When a caller or sender is blocked: inbound calls are rejected before they connect, and inbound texts are stored but never delivered to the agent. No text.received webhooks fire, identity-scoped keys never see the blocked rows, and admin API keys or the Inkbox Console can audit them with is_blocked=true filters on the calls and texts listings.

The identity needs a phone number. Phone contact rules and phone_filter_mode only apply to an identity that has a phone number. While an identity has no number, creating a rule (or setting phone_filter_mode) returns 422, listing rules returns an empty list, and addressing a specific rule returns 404. Assign a number first — see Phone numbers.

Deprecated. The per-number routes under /numbers/{phone_number_id}/contact-rules are deprecated. Use the handle-keyed routes documented below instead.

Auth. List, get, and create accept admin API keys and claimed agent keys; unclaimed (mid-signup) agent keys are rejected. PATCH, DELETE, and the org-wide list require an admin-scoped API key, or you can manage them as a user in the Inkbox Console.

GET /identities/{agent_handle}/phone-contact-rules

List contact rules for an agent identity, newest first. Returns an empty list while the identity has no phone number.

An identity-scoped API key may only address its own identity's agent_handle — any other handle returns 403 (this applies to list, get, and create alike).

Path parameters

Query parameters

Response (200)

JSON

Code examples

cURL

cURL

Python

TypeScript

POST /identities/{agent_handle}/phone-contact-rules

Add an allow or block rule for an agent identity. New rules are always created active; use update to pause one.

Path parameters

Request body

Request example

JSON

Response (201)

Returns the new rule. See Contact rule object.

Error responses

Code examples

cURL

cURL

Python

TypeScript

GET /identities/{agent_handle}/phone-contact-rules/{rule_id}

Fetch a single rule by ID.

Path parameters

Response (200)

Returns the rule. See Contact rule object.

Error responses

PATCH /identities/{agent_handle}/phone-contact-rules/{rule_id}

Change a rule's action or status. Requires an admin API key, or manage rules from the Inkbox Console. 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 field is required; fields you omit are left unchanged.

Request example

JSON

Response (200)

Returns the updated rule.

Error responses

DELETE /identities/{agent_handle}/phone-contact-rules/{rule_id}

Delete a rule. Requires an admin API key, or manage rules from the Inkbox Console.

Path parameters

Response (204)

No content.

Error responses

GET /phone/contact-rules

Org-wide aggregate list of phone contact rules across every identity. Intended for admin dashboards that render rules org-wide without fanning out one request per identity. Requires an admin API key, or browse rules in the Inkbox Console.

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

Query parameters

Response (200)

Returns a list[ContactRule] ordered newest first — same shape as the per-identity list.

Code examples

cURL

cURL

Python

TypeScript

• Phone guide — Filtering inbound calls and texts — narrative walk-through of whitelist/blacklist semantics
• Manage identities — set phone_filter_mode
• iMessage contact rules — the identity-scoped equivalent for iMessage
• Mail contact rules — the mail-side equivalent