Foyer API

Authentication and permissions

Each key belongs to one Foyer member and can only see that member's account. You choose what each key may do when you make it.

API keys

Send the key in the Authorization header: Authorization: Bearer fyr_…. Keys are never accepted in the URL.
Make keys in the Foyer app or dashboard under Settings › Connected apps. A key is shown once; Foyer stores only a fingerprint of it.
A key lasts 90 days, or less if you choose. You can revoke it at any time, and it stops working at once.
You can have up to 10 active keys. Use one key per app or script, so you can see what each one did and revoke one without breaking the others.
Keys cannot make or revoke keys. Managing keys needs your signed-in Foyer app or dashboard.
Connected apps shows when each key was last used and what it did, for example how many calls and voicemails it read. The activity log records the request, not the content.

Permissions (scopes)

A request without the permission it needs gets 403 insufficient_scope, with the missing permission in details.required_scope.

Permission	Shown as	What it covers	Plan
`calls:read`	See your calls, summaries and voicemails list	Calls, outcomes and summaries, the voicemails list, the review queue, call counts, and search over names, numbers and summaries.	Every plan
`transcripts:read`	Read conversations and voicemail text	The screening conversation, voicemail text and the recorded call's transcript. Search also looks inside them.	Every plan
`audio:read`	Listen to recordings	Links that play a recording for five minutes. Off unless you tick it.	Every plan
`contacts:read`	See your contacts and how Foyer treats each one	Contacts, approved and blocked callers, remembered callers and personal greetings.	Every plan
`settings:read`	See your settings, numbers and what your host knows	Every setting, your Foyer number and forwarding lines, your notes and the facts your host knows.	Every plan
`calls:write`	Mark, archive, refile and report calls	Mark read or unread, archive, mark a voicemail heard, refile a call and report spam.	Concierge or Chief of Staff
`contacts:write`	Change how Foyer treats callers	Add contacts, approve or block callers, screen a contact like a stranger for a while, and manage personal greetings.	Concierge or Chief of Staff
`settings:write`	Change your Foyer settings	Any setting you can change in the app: screening, greeting, voice, recording, ringing, notifications, pausing and your lines.	Concierge or Chief of Staff
`notes:write`	Add and edit notes and facts for your host	Tell your host things and accept, edit or drop the facts it has learned.	Concierge or Chief of Staff

Two things to know:

Words are separate from calls. With calls:read alone, an agent sees who called, the outcome and the summary. It needs transcripts:read to read what callers said. Without it, a call comes back with transcripts_omitted: true, and search covers names, numbers and summaries only.
Recordings are separate again. audio:read is off unless you tick it. With it, an agent gets a link that plays one recording for five minutes; treat that link like a password.

Plans

Plan	Price	What the API and connector can do
Doorman	$5.99 a month	Read: calls, voicemails, transcripts, contacts, settings and search
Concierge	$12.99 a month	Read and change: everything Doorman reads, plus every setting you can change in the app
Chief of Staff	$19.99 a month	Read and change, the same as Concierge

On Doorman, a request that would change something gets 403 plan_does_not_include_writes, and nothing on your account changes. A key made with write permissions keeps them, and they work again after an upgrade. The free first month and complimentary access count as Chief of Staff.

To see what the key in use may do right now, call GET /v1/me. It returns the key's permissions, access.writes_allowed and your limits.

Claude, ChatGPT and other assistants connect through the MCP connector instead of a key: you sign in with your Foyer account and approve the permissions on a consent screen. The same permissions and limits apply. See Connect Claude or ChatGPT.

Errors

Every error has the same shape: {"error": {"code": "…", "message": "…", "status": 403, "details": {}}}. code is stable; message is written for people and may change.

Status	Code	What it means
400	`invalid_request`	Something is missing, or a value is not one Foyer accepts.
401	`unauthorized`	No key, or the key is wrong, revoked or expired.
402	`plan_required`	This feature is not in your plan.
403	`insufficient_scope`	The key lacks the permission named in `details.required_scope`.
403	`plan_does_not_include_writes`	Your plan reads only. Nothing was changed.
403	`api_not_enabled`	The API is not open on this account yet. During the preview it is open to preview members only.
403	`forbidden`	The app itself refuses this change, for example a feature that is not available on this line.
404	`not_found`, `media_not_found`	No such call, contact or recording on this account.
409	`conflict`, `key_limit`	The change conflicts with the account's current state, or you already have 10 active keys.
410	`link_expired`	A recording link expired, or the key that made it lost `audio:read`. Ask for a new one.
429	`rate_limited`	Over a limit. Wait the seconds in the `Retry-After` header. See Limits.
500, 503	`server_error`, `unavailable`	Something failed on Foyer's side. Safe to retry later.

Good practice

Give each key only the permissions it needs. A summary script needs calls:read, not settings:write.
Keep keys in environment variables or a secrets manager, never in code you share or in a URL.
Revoke a key as soon as you stop using it, or if it may have leaked.