---
title: "Access"
description: "Who can reach an agent by phone — block and allow rules, and allowlist mode where only allowed numbers get through."
canonical_url: "https://www.agent-identity.dev/docs/phone/access"
markdown_url: "https://www.agent-identity.dev/docs/phone/access.md"
last_updated: "2026-10-09"
x_farming_labs_generated_preamble: true
agent:
  tokenBudget: 800
  task: "Block a phone number, allow one, or let only allowed numbers reach an agent."
  outcome: "A blocked or not-allowed caller is refused before the call connects, and calls placed to a blocked number fail with 403."
  appliesTo:
    package:
      - "@aid/api"
      - "@agentidentity/sdk"
  prerequisites:
    - "An org key to create rules."
  files:
    - "apps/api/src/services/phone.ts"
  sideEffects:
    - "Refused calls are recorded with is_blocked true and write no events."
  verification:
    - description: "List blocked calls."
      expect: "GET /v1/identities/{id}/calls?is_blocked=true lists the refused calls (org key only)."
  rollback:
    - "DELETE /v1/contact-rules/{id} removes a rule. PUT filter_mode blocklist turns allowlist mode off."
  failureModes:
    - symptom: "Every incoming call is refused."
      resolution: "The agent is in allowlist mode and the caller has no allow rule. Add one, or set filter_mode to blocklist."
    - symptom: "403 when placing a call."
      resolution: "A block rule matches the number you are calling. Remove it to call."
---

# Access
URL: /docs/phone/access
LLM index: /llms.txt
Description: Who can reach an agent by phone — block and allow rules, and allowlist mode where only allowed numbers get through.
Related: /docs/phone/incoming-calls, /docs/mail/contacts, /docs/phone/calls-and-events

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Block a phone number, allow one, or let only allowed numbers reach an agent.
Outcome: A blocked or not-allowed caller is refused before the call connects, and calls placed to a blocked number fail with 403.

### Applies To

- Package: `@aid/api`, `@agentidentity/sdk`

### Prerequisites

- An org key to create rules.

### Files

- `apps/api/src/services/phone.ts`

### Side Effects

- Refused calls are recorded with is_blocked true and write no events.

### Verification

- List blocked calls.
  - Expected: GET /v1/identities/{id}/calls?is_blocked=true lists the refused calls (org key only).

### Rollback

- DELETE /v1/contact-rules/{id} removes a rule. PUT filter_mode blocklist turns allowlist mode off.

### Failure Modes

- Every incoming call is refused. — Recovery: The agent is in allowlist mode and the caller has no allow rule. Add one, or set filter_mode to blocklist.
- 403 when placing a call. — Recovery: A block rule matches the number you are calling. Remove it to call.
<!-- farming-labs:agent-contract:end -->

# Access

Phone access uses the same rules as email, with `channel: "phone"`. A rule matches one exact E.164 number and covers calls
in both directions.

## Block or allow a number

```ts title="rules.ts"
await org.contactRules.create({ identityId: agent.id, channel: "phone", matchAddress: "+14155550111", action: "block" });
await org.contactRules.create({ identityId: agent.id, channel: "phone", matchAddress: "+14155550123", action: "allow" });
```

```bash title="terminal"
curl -sS -X POST https://api.agent-identity.dev/v1/contact-rules \
  -H "authorization: Bearer $AID_ORG_KEY" -H 'content-type: application/json' \
  -d '{"identity_id":"'$AID_AGENT'","channel":"phone","match_address":"+14155550111","action":"block"}'
```

Leave out `identity_id` for a rule that applies to every agent in the organization. An agent's own rule wins over an
organization-wide one; between rules of the same level, block wins.

## Only let allowed numbers through

`filter_mode` on the [incoming call setting](/docs/phone/incoming-calls) chooses what happens to numbers no rule
mentions:

| `filter_mode` | Who gets through |
| --- | --- |
| `blocklist` | Everyone except blocked numbers. The default. |
| `allowlist` | Only numbers with an allow rule. |

```ts title="allowlist.ts"
await org.phone.setIncomingCallAction(agent.id, { incomingCallAction: "hosted_agent", filterMode: "allowlist" });
```

`whitelist` and `blacklist` are still accepted as input and read back as `allowlist` and `blocklist`.

## What a refused call looks like

A blocked or not-allowed caller is refused before the call connects: no webhook, no WebSocket, no events. The call is
recorded with `hangup_reason: "rejected"` and `is_blocked: true`.

Org keys can list them with `GET /v1/identities/{id}/calls?is_blocked=true`. Agent keys never see blocked calls.

## Calls you place

A call to a number with a block rule fails with 403. Allowlist mode applies to incoming calls only.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).