Docs / Guides

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.

See yours first

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

ScopeGrants
call_settings:readListing flows, and seeing which one answers each persona.
call_settings:writeChanging 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"
}
  • type is custom for your own flows; for a preset it's what it does: ring_in_phound, one_number, forward, meeting, message or voicemail.
  • config is the flow's steps as the Phound app builds them: main names the step a call starts at, extensions holds 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}'
typeCalls areFields
ring_in_phoundRung in the Phound app — what a persona never given a flow does.
forwardForwarded 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.
messagePlayed a message; then the call ends. text to read aloud, or the url (https) of an audio file — one of them.
voicemailSent straight to the persona's voicemail.
meetingPut straight into the persona's meeting.
one_numberOffered a menu: 1 to ring the persona, 2 for voicemail, 3 for its meeting.
customAnswered 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.

Forwarding costs money

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.

What voicemail plays

Flows that send callers to voicemail play the persona's own greeting. Change it, or turn voicemail off, with the voicemail settings.

Errors

StatusWhen
400 validation_failedA malformed request: an unknown field, a number without its +, a strategy that doesn't exist.
404 persona_not_foundNot one of your own personas.
404 flow_not_foundA flow_id that isn't one of your flows.
422 validation_failedA 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.