Call flows
A call flow decides what happens when someone calls one of your personas: ring it in the Phound app, forward the call, play a message, take a voicemail. The Calls API lists your flows and Phound's presets, shows which one answers each persona, and switches it — say, forwarding calls to your phone after hours, or playing a message while you're closed.
The dashboard is built on the same API: its Call flows page lists your flows and the personas each answers, and each persona's page under Personas switches the one that answers it.
Scopes
| Scope | Grants |
|---|---|
call_settings:read | Listing flows, and seeing which one answers each persona. |
call_settings:write | Changing a persona's flow. Never implied: a forward flow
dials any number you give it, charged to your Phound balance — give it to a key only if it needs it. |
List flows
Your own flows — built in the Phound app — and Phound's presets, the same for every account:
curl "https://api.phound.app/calls/v1/flows" \
-H "Authorization: Bearer $PHOUND_KEY"
type=custom lists only your own; any other type, only the presets of that type. Every flow fits in
one page.
A flow
{
"id": "sU91raib",
"object": "flow",
"name": "Forward",
"description": null,
"type": "forward",
"preset": true,
"config": {
"main": "1650f2d3-a0ee-46d3-bcc7-cd90f0de35dc",
"version": 2,
"extensions": { "1650f2d3-a0ee-46d3-bcc7-cd90f0de35dc": { "type": "dial", "…": "…" } }
},
"created_at": "2025-05-14T10:02:11Z",
"updated_at": "2025-05-14T10:02:11Z"
}
typeiscustomfor your own flows; for a preset it's what it does:ring_in_phound,one_number,forward,meeting,messageorvoicemail.configis the flow's steps as the Phound app builds them:mainnames the step a call starts at,extensionsholds them by id. Read it, but don't depend on its details yet — it isn't a stable contract and may gain step types and fields.
Change it
PUT /personas/{persona_id}/flow sets how the persona's calls are answered, from its next call on: a
type, and that type's fields.
curl -X PUT https://api.phound.app/calls/v1/personas/1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c/flow \
-H "Authorization: Bearer $PHOUND_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "forward", "numbers": ["+14155550100"], "timeout": 20}'
type | Calls are | Fields |
|---|---|---|
ring_in_phound | Rung in the Phound app — what a persona never given a flow does. | |
forward | Forwarded to other numbers. | numbers (required): up to 20, in E.164 like +14155550100.strategy: simultaneous (the default) rings them all at once, sequence
one at a time in their order, distribute one at a time in random order.timeout: seconds to ring, 1 to 300; 30 if not given. |
message | Played a message; then the call ends. | text to read aloud, or the url (https) of an audio file — one of
them. |
voicemail | Sent straight to the persona's voicemail. | |
meeting | Put straight into the persona's meeting. | |
one_number | Offered a menu: 1 to ring the persona, 2 for voicemail, 3 for its meeting. | |
custom | Answered by one of your own flows. | flow_id (required): its id from GET /flows. |
A field another type takes is refused, so a typo can't be silently ignored. The persona must be active.
Calls forwarded over the phone network are charged to your Phound balance, like any call you make.
See how a persona's calls are answered
curl https://api.phound.app/calls/v1/personas/1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c/flow \
-H "Authorization: Bearer $PHOUND_KEY"
{
"object": "active_flow",
"persona_id": "1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c",
"type": "forward",
"numbers": ["+14155550100"],
"strategy": "simultaneous",
"timeout": 20,
"flow": { "id": "sU91raib", "object": "flow", "name": "Forward", "type": "forward", "…": "…" }
}
The same fields PUT takes, read back, and the flow itself, filled in for the persona.
numbers lists phone numbers only — a Phound user set up in the app to be rung isn't shown.
type and flow are null when the persona uses a flow set up in the Phound
app that this API doesn't offer yet.
Only your own personas — not ones other Phound users share with you, whose calls are theirs.
Flows that send callers to voicemail play the persona's own greeting. Change it, or turn voicemail off, with the voicemail settings.
Errors
| Status | When |
|---|---|
400 validation_failed | A malformed request: an unknown field, a number without its
+, a strategy that doesn't exist. |
404 persona_not_found | Not one of your own personas. |
404 flow_not_found | A flow_id that isn't one of your flows. |
422 validation_failed | A field the type doesn't take, or one it needs is
missing — errors[].pointer names it; the persona isn't active; or Phound won't run the flow.
detail says why. |