Pull calls into your own reports

If you keep your own reports, you can pull every call out of Foan on a schedule: who was called, how it went, the summary, the transcript and the recording. Everything here only reads data. It never places calls or changes anything.

You will need: someone comfortable running requests from a script or server, and an API key with calls:read and recordings:read (add campaigns:read if you run campaigns). See API keys. The same guide, with your own key filled in, is under Developers > Docs in the dashboard.

In the examples, $FOAN_KEY is your API key and $ORG_ID is your organisation ID. Every request goes to https://api.foan.ai/api/v1.

1. Find your organisation ID

Ask the API who the key belongs to. The answer includes your organisationId and the key’s scopes.

curl -s "https://api.foan.ai/api/v1/api-keys/me" \
  -H "Authorization: Bearer $FOAN_KEY"

2. List calls for a date range

Dates are ISO 8601. Add your time zone offset so the day starts at your midnight (a + is written %2B in a web address). A page holds up to 100 calls; keep raising page until you pass pagination.totalPages.

curl -s "https://api.foan.ai/api/v1/call-history/sessions/organization/$ORG_ID?startDate=2026-09-20T00:00:00%2B01:00&endDate=2026-09-20T23:59:59%2B01:00&limit=100&page=1" \
  -H "Authorization: Bearer $FOAN_KEY"

Useful filters: callDirection=OUTBOUND or INBOUND; outcome=answered, no_answer, busy, rejected, voicemail or failed; agentId; campaignsOnly=true; excludeCallType=chat; search (name, number or Call ID).

The fields most reports use:

Field	Meaning
roomName	The Call ID shown in the dashboard. Use it to fetch the transcript.
id	The call’s record ID, used for the recording.
phoneNumber, participantName	Who was called, or who called.
callDirection	Outbound or inbound.
createdAt, endedAt, callDuration	When it started and ended; duration in milliseconds.
callOutcome	What happened on the line, for example completed, no_answer or busy.
overview.score	A call score from 1 to 10, empty when there was no conversation.
overview.summary	A short summary, one line per point.
customVariables	The values you passed when the call was placed, such as an order number.
recordingUrl	Where to download the recording.

3. Read a transcript

Every line in spoken order: assistant is your agent, user is the other person.

curl -s "https://api.foan.ai/api/v1/call-history/sessions/room/<Call ID>/transcripts" \
  -H "Authorization: Bearer $FOAN_KEY"

4. Download a recording

Fetch the call’s recordingUrl with the same key. It needs recordings:read.

curl -s -o call.ogg "https://api.foan.ai/api/v1/voice-sessions/<id>/recording" \
  -H "Authorization: Bearer $FOAN_KEY"

5. Or export to Excel in one request

The export takes the same filters and returns up to 10,000 calls, one row each, as an Excel file: a quick sheet for people to read. To join calls to your own records, use the list in step 2, which carries overview and customVariables.

curl -s -o calls.xlsx "https://api.foan.ai/api/v1/call-history/sessions/organization/$ORG_ID/export?startDate=2026-09-20T00:00:00%2B01:00&endDate=2026-09-26T23:59:59%2B01:00" \
  -H "Authorization: Bearer $FOAN_KEY"

If you run campaigns, a key with campaigns:read can also list your campaigns, each campaign’s contacts with their latest result, and campaign totals. See the API reference.

Common failures

A request returns 403

The organisation ID is not the key’s own organisation. A key only ever sees its own organisation. Use the organisationId from step 1, and check the key’s scopes under Developers > API Keys.

A transcript request returns 404

The Call ID belongs to another organisation, or you used the record id instead of roomName. Use roomName for transcripts.

The overview is empty on a recent call

Every call is analysed automatically a few minutes after it ends. Fetch it again later.

Next steps

• API keys: create the read-only key.
• API reference: every request in full.
• Export calls: the same export from the dashboard, no code needed.