> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask by phone number

> Ask a person to approve an action or an agent's proposal by the phone number they gave you, without learning whether the number belongs to anyone.

> [!NOTE]
>
> In pilots. Asking by phone number is enabled for pilot companies. Ask us to turn it on for yours.

When a customer gives you their phone number, for example on a support call or in a chat with your agent, you can ask them to approve by that number instead of by your own user ref. BotShield looks the number up once and drops it. No answer tells you whether anyone holds it: every ask gets the same answer, and you show the person a two-digit number to pick in the BotShield app before they can approve.

Two operations take a `phone_number`:

| Operation | Key | In place of |
| - | - | - |
| [`POST /gates-api/actions/request`](https://docs.botshield.ai/actions/ask-through-an-agent) | API key with Gates API access | `partner_user_ref` |
| [`POST /agentlink/inquire`](https://docs.botshield.ai/agents-ask/propose-an-action) | Agent key | `partner_user_ref` or `opaque_id` |

Name the person one way only. A request with `phone_number` and any other way to name the person is refused with `one_addressee_required`.

## Ask

```bash curl theme={null}
curl -s https://api.botshield.ai/operations/gates-api/actions/request \
  -H "Authorization: Bearer $BOTSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "8e1f4b2c-6a3d-4c5e-9f70-1a2b3c4d5e6f",
    "agent": "MeridianConcierge",
    "act": "plan-change:acct_1182:4be0c9",
    "act_label": "Change your plan",
    "phone_number": "+1 415 555 0142",
    "details": [
      { "label": "Plan", "value": "Family, monthly" },
      { "label": "Total", "value": "$24.00 a month" }
    ]
  }'
```

```json theme={null}
{
  "data": {
    "data": {
      "request_id": "8e1f4b2c-6a3d-4c5e-9f70-1a2b3c4d5e6f",
      "status": "queued",
      "expires_at": "2026-11-18T19:10:00.000Z",
      "match_number": 47
    }
  }
}
```

`agentlink/inquire` answers the same way, with `status: "queued"`, `card_id`, `ttl_at`, `request_id` and `match_number`.

The answer is the same whether or not anyone holds the number, and every answer takes about the same time. Send the number with the country code when it is outside the US. BotShield checks only the number's form: an international number with `+` and the country code, or 10 digits (or 11 starting with `1`) for the US and Canada. A malformed number is refused with `phone_invalid`.

## Show the match number

Show `match_number` to the person where you are talking to them: on your screen, in your agent's conversation, or read aloud on the call. In the BotShield app, the card shows three two-digit numbers. The person picks yours, then approves with their passkey.

A wrong pick ends the request: it reads `denied`, and no token or proof is issued. This is what stops someone from approving an ask that was meant for another conversation.

## What the person receives

What happens next depends on who holds the number, and none of it changes the answer you got.

| The number belongs to | What happens |
| - | - |
| A person who is BotShield Verified with your company and has not removed this agent | The card, under the same [limits per person](https://docs.botshield.ai/actions/ask-through-an-agent.md#limits-per-person) as any other ask. |
| A person who is BotShield Verified with your company and removed this agent | Nothing. |
| A person who is not BotShield Verified with your company | An **introduction** only, never the card. The introduction names your company. If the person allows it, with their passkey, they become BotShield Verified with your company and the ask becomes the card. If they block it, nothing more from your company reaches them by number. |
| Nobody | Nothing. |

## Read the status

Read the status with `GET /gates-api/actions/request-status` or `GET /agentlink/check-status`, as for any ask. Until a card exists, the request reads `queued`, then `expired` when `expires_at` passes. That is the same for a number nobody holds, an introduction that is never allowed, a person who blocked you, and a card a limit stopped. Once the card exists, it reads as itself: `approved`, `denied`, `expired` or `cancelled`.

Withdraw a request the usual way, with `gates-api/actions/request-cancel` or `agentlink/cancel`. It is withdrawn the same whether or not a card was ever made.

## Rules

* **The number is used once.** BotShield uses it for one lookup, then drops it. It is never stored, logged or sent in a webhook.
* **High-value actions are never asked by number.** An action marked [high-value](https://docs.botshield.ai/actions/place-an-action.md#high-value-actions) is refused with `action_requires_signed_in` before anything about the number is read. Ask for it with `partner_user_ref`, from your customer's signed-in session.
* **Production needs a verified business.** In Production, only an organization that has passed business verification can ask by phone number. Development keys and development agents can ask without it.
* **Your company's limits.** Asks by phone number are limited per API key or agent per hour (`send_rate_limited`), and by how many of your company's asks by number in the last 24 hours went unanswered (`unanswered_limit_reached`). Both answer HTTP status `429` with `retry_after_seconds`, and nothing is sent.
* **One `request_id`, one way.** A `request_id` already used with a user ref or an `opaque_id` cannot be reused by number, and the reverse. Both are refused with `request_id_reused`.

## Error codes

Errors arrive as `data.error` with HTTP `200`. These are the codes particular to asking by phone number. The other codes of each operation are listed on [Ask through an agent](https://docs.botshield.ai/actions/ask-through-an-agent.md#error-codes) and [Propose an action](https://docs.botshield.ai/agents-ask/propose-an-action.md#errors).

| `code` | `statusCode` | Cause |
| - | - | - |
| `one_addressee_required` | 400 | `phone_number` was sent with another way to name the person, or (on `gates-api/actions/request`) with neither. |
| `phone_invalid` | 400 | The number is malformed: not `+` and a country code, and not a 10- or 11-digit US or Canada number. |
| `action_requires_signed_in` | 403 | The action is high-value. `gates-api/actions/request` only. |
| `org_not_verified` | 403 | Production: your business has not passed verification, or the agent is not registered to a company. |
| `send_rate_limited` | 429 | Too many asks by phone number from this key or agent in the last hour. |
| `unanswered_limit_reached` | 429 | Too many of your company's asks by phone number in the last 24 hours were not answered. |
| `request_id_reused` | 409 | This `request_id` was already used for a different request. |
| `unavailable` | 503 | BotShield is unavailable right now. Try again in a moment. |

## Next steps

> [card] [Ask through an agent](https://docs.botshield.ai/actions/ask-through-an-agent.md)
>
> The full request, the terms, the token and withdrawing.

> [card] [Propose an action](https://docs.botshield.ai/agents-ask/propose-an-action.md)
>
> Your agent's own proposal, with `phone_number`.

> [card] [Place an action](https://docs.botshield.ai/actions/place-an-action.md)
>
> Mark an action high-value.

> [card] [Privacy boundary](https://docs.botshield.ai/concepts/privacy-boundary.md)
>
> What BotShield never tells you about a person.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.