---
title: "Arm Phone testing: pin one declared caller number to the workflow"
method: POST
path: "/v1/agents/{agent_id}/workflow/phone-pin"
---

# Arm Phone testing: pin one declared caller number to the workflow

`POST /v1/agents/{agent_id}/workflow/phone-pin`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/agents/{agent_id}/workflow/phone-pin`
- Auth: none declared

The next matching inbound call to the ONE number this pin names -- from exactly this caller number, within the TTL -- is answered by a fresh run of the pinned draft or published workflow instead of the agent's normal configuration. Every other caller is unaffected, and so is every other number attached to the same agent: an agent serving both a test line and a production line never exposes an unpublished draft on the production line. from_e164 is declared by the authenticated workspace member arming it, not independently verified (this is a test aid on a phone_test_eligible number, not an access-control boundary). Arming again while a pin is still active supersedes it -- at most one active pin per agent. Fails closed if the draft workflow does not currently compile.

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `from_e164` string, required: The caller number this pin matches, in any recognizable phone format.
  - `number_id` string, required: The workspace number this test answers on. Must be attached to this agent and phone-test eligible.
  - `pinned_source` 'draft' | 'published'
  - `ttl_seconds` integer

## Response `201`

Pin armed

## Other responses

- `400`: Missing from_e164 or number_id, a number that cannot answer this agent's phone test, or a draft workflow with validation errors
- `404`: Agent has no workflow yet, no published version yet, or the number is not in this workspace

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/95b8c66f99aa?raw)