API reference
Foan’s REST API lets your own systems place calls, read every call’s outcome, score, summary, transcript and recording, run campaigns and manage agents, numbers and billing.
Base URL https://api.foan.ai/api/v1
Authentication. Create an API key in the dashboard under Developers, API keys, and send it on every request as Authorization: Bearer foan_prod_.... A key belongs to one organisation and carries scopes; each endpoint below names the scope it needs. A key never sees another organisation’s data: a foreign organisation ID answers 403 and a foreign call ID answers 404. A key bound to one agent acts for that agent only: another agent’s agent, results or call routes answer 403, agent lists and counts show only its own agent, and it cannot create or duplicate agents.
Responses. JSON bodies use { "success": true, "data": ... }. Errors use { "success": false, "error": "..." } (a few older routes send message instead of error). Lists page with page and limit (up to 100) unless the endpoint says otherwise.
Rate limits. 200 requests a minute per client by default; endpoints that spend money or run AI allow fewer (about 20 to 30 a minute). A 429 means wait and retry.
Reporting. To pull calls into your own reports, see the Calls endpoints: list calls for a date range, then fetch each call’s transcript and recording, or download everything as one Excel file.
Base URL: https://api.foan.ai/api/v1
Endpoints by area
Section titled “Endpoints by area”| Area | Endpoints | What it covers |
|---|---|---|
| Calls | 19 | Call history, transcripts, per-call results, search and export. Placing calls needs calls:create; reading needs calls:read. |
| Recordings | 1 | Stream a call recording through Foan. Needs recordings:read. |
| Results | 4 | What each agent achieved on its calls, in the outcomes and details the agent tracks (its resultsConfig or call flow): totals, rows and CSV export. Needs calls:read. |
| Analytics | 2 | Re-run the AI analysis of a finished call on demand. Every call is already analysed after it ends, so reporting does not need these. |
| Agents | 15 | Voice and chat agents: list, read, create, update, clone and delete. |
| Campaigns | 25 | Outbound calling campaigns, their contacts, per-contact results, follow-ups and extracted data. |
| Knowledge | 4 | Knowledge bases your agents answer from. |
| Catalogues | 5 | Product catalogues your agents can search. Reading needs knowledge:read; creating and uploading needs knowledge:write. |
| Phone numbers | 33 | Buy, connect and route phone numbers. Several of these spend money immediately. |
| SIP | 3 | Your SIP trunk configuration. |
| Organisation | 4 | Your organisation and its pending invitations. |
| Members | 9 | People in your organisation and their roles. |
| Billing | 17 | Billing profile, rates, status and usage. |
| Wallet | 6 | Wallet balance, transactions and top-ups. |
| Widget | 5 | Public chat and web-call widget endpoints (widget tokens only). |
| API keys | 1 | Inspect the key you are using and manage widget tokens. |
| AI enhancement | 2 | Rewrite agent configuration text with AI. |
| Webhooks | 1 | Webhook processor status. |
156 endpoints in total. Get a key under API keys.