Endpoint reference

GET /v1/openapi.json

This specification as JSON

Operation

get_openapi_spec

Auth

None: public

The OpenAPI 3.1 document for this API. No authentication.

Returns

200 The OpenAPI document.

curl "https://api.hifoyer.com/v1/openapi.json"

GET /v1/me

What this key can do

Operation

get_me

Auth

Any API key

The key in use, which scopes it has, whether the member's plan allows changes, and the rate limits. Call this first to learn what you may do. Needs no particular scope.

Returns

200 The key and its permissions.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/me" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/calls

List screened calls

Operation

list_calls

Auth

API key with calls:read

The member's calls, newest first, with who called, what Foyer did with the call (outcome) and a one-line summary. Filter by outcome, date, read state, voicemail or caller. Archived calls are left out unless archived says otherwise. Listing never marks calls read.

Parameters

Returns

200 One page of calls, newest first.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/calls" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/voicemails

List calls that left a voicemail

Operation

list_voicemails

Auth

API key with calls:read

Calls where the caller left a voicemail, newest first. Same shape and filters as GET /v1/calls. Use voicemail.reviewed to find new ones; read the message text with GET /v1/calls/{id} (needs transcripts:read) or listen with GET /v1/calls/{id}/audio?part=voicemail.

Parameters

Returns

200 One page of calls, newest first.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/voicemails" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/review

Calls waiting for the member's review

Operation

list_review_queue

Auth

API key with calls:read

Calls Foyer was unsure about and held for the member (outcome = review) that the member has not looked at yet, newest first. To clear one, mark it read; to decide what happens next time this caller rings, refile it (POST /v1/calls/{id}/refile).

Parameters

Returns

200 One page of calls, newest first.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/review" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/calls/{id}

One call in full

Operation

get_call

Auth

API key with calls:read

Everything about one call: the caller, the outcome and summary, which forwarding line it came in on, what went wrong if anything (incidents), the voicemail, recordings and which audio parts exist. With transcripts:read it also has the words: the screening conversation between Foyer and the caller, the voicemail text and the transcript of the recorded connected call. Without that scope those fields are left out and transcripts_omitted is true. Reading a call here does NOT mark it read.

Parameters

Returns

200 The call.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/calls/CALL_ID" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/search

Search calls by words

Operation

search_calls

Auth

API key with calls:read

Finds calls whose caller name, caller ID, company, number or summary contain q (case-insensitive, the whole phrase). With transcripts:read it also looks inside voicemail text, the screening conversation and the recorded call's transcript, and each hit carries a short excerpt around the match.

Calls are stored encrypted, so search examines up to 400 calls per request, newest first. If next_cursor is not null, more history remains: pass it back as cursor to keep searching further back. search.reached_oldest_call says when there is nothing older. Combine with since/until or outcome to narrow the scan. Counts against the search limit of 20 a minute.

Parameters

Returns

200 Matching calls, newest first.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/search?q=plumber" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/stats

Call counts today and overall

Operation

get_call_stats

Auth

API key with calls:read

How many calls Foyer handled today (put through, held for review, sent to voicemail, blocked) and since the member joined.

Parameters

Returns

200 The counts.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/stats" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/calls/{id}/mark-read

Mark a call read

Operation

mark_call_read

Auth

API key with calls:write

Plan

Concierge or Chief of Staff (changes data)

Clears the unread dot on every device, exactly like opening the call in the app. Idempotent; returns when it was first read.

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/calls/CALL_ID/mark-read" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/calls/{id}/mark-unread

Mark a call unread

Operation

mark_call_unread

Auth

API key with calls:write

Plan

Concierge or Chief of Staff (changes data)

Shows the call as unread again on every device (and its voicemail as new).

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/calls/CALL_ID/mark-unread" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/calls/{id}/archive

Archive a call

Operation

archive_call

Auth

API key with calls:write

Plan

Concierge or Chief of Staff (changes data)

Moves the call out of the member's lists into Archived on every device. Nothing is deleted; unarchive brings it back.

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/calls/CALL_ID/archive" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/calls/{id}/unarchive

Unarchive a call

Operation

unarchive_call

Auth

API key with calls:write

Plan

Concierge or Chief of Staff (changes data)

Returns an archived call to the member's lists.

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/calls/CALL_ID/unarchive" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/calls/{id}/voicemail/mark-reviewed

Mark a voicemail heard

Operation

mark_voicemail_reviewed

Auth

API key with calls:write

Plan

Concierge or Chief of Staff (changes data)

Marks this call's voicemail as reviewed, so it no longer counts as a new message.

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/calls/CALL_ID/voicemail/mark-reviewed" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/calls/{id}/refile

Tell Foyer how this caller should be handled

Operation

refile_call

Auth

API key with calls:write

Plan

Concierge or Chief of Staff (changes data)

Re-files the call and sets the caller's treatment for next time, the same as the choices on a call in the app: through approves the caller (rings straight through from now on); screened treats them as a stranger (screened every time); review holds their calls for the member's review; voicemail files the call as voicemail; block blocks the caller (turned away from now on). Foyer learns from these choices.

Parameters

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/calls/CALL_ID/refile" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"through"}'

POST /v1/calls/{id}/report-spam

Report the caller as spam

Operation

report_spam

Auth

API key with calls:write

Plan

Concierge or Chief of Staff (changes data)

Files a spam report for this call's caller, which helps protect every Foyer member. Returns how many households have reported the number. Idempotent.

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/calls/CALL_ID/report-spam" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/calls/{id}/audio

A five-minute link to a recording

Operation

get_call_audio_link

Auth

API key with audio:read

Returns a URL that plays one recording of this call for the next five minutes, without further authentication. Fetch it promptly; it answers with a redirect to the audio file (or the audio itself). Ask again for a new link when it expires. Needs audio:read, which members grant separately. GET /v1/calls/{id} lists the parts that exist in audio_parts.

Parameters

Returns

200 The link.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/calls/CALL_ID/audio?part=voicemail" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/audio

Play a recording from a link

Operation

play_audio_link

Auth

The signed link itself (no header)

The URL returned by GET /v1/calls/{id}/audio, used as given. The link is its own credential for five minutes; no Authorization header is needed. It stops working when it expires, when the key that made it is revoked or loses audio:read, or when the account closes.

Parameters

Returns

200 The audio (supports HTTP Range).

Errors

• 302 Redirect to the audio file at a short-lived storage URL.
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 410 The link expired or is no longer allowed (link_expired).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/audio?link=example"

GET /v1/contacts

Contacts and how Foyer treats them

Operation

list_contacts

Auth

API key with contacts:read

Everyone who rings straight through (saved contacts and approved callers), sorted by name, with their treatment: through, or appear_unknown while the member has asked Foyer to screen them like a stranger for a while. personalized means they have a personal greeting or answering setup. The first page also lists blocked numbers. Every other caller is a stranger and is screened.

Parameters

Returns

200 One page of contacts.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/contacts" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/contacts

Add a contact

Operation

add_contact

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

Saves a contact; they ring straight through from now on. It is also added to the member's iPhone contacts at the next sync.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/contacts" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100"}'

POST /v1/contacts/archive

Remove a contact (archive)

Operation

archive_contact

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

Takes the number out of contacts and clears any approval or block, so the caller is screened like a stranger. Reversible with restore.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/contacts/archive" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100"}'

POST /v1/contacts/restore

Restore an archived contact

Operation

restore_contact

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

Brings an archived contact back under its saved name; they ring straight through again.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/contacts/restore" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100"}'

POST /v1/contacts/approve

Let a caller ring straight through

Operation

approve_caller

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

Approves a number (the "Through" choice on a contact). Clears a block on it.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/contacts/approve" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100"}'

POST /v1/contacts/unapprove

Screen a caller again

Operation

unapprove_caller

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

Removes the approval, so Foyer screens this number like any stranger. To hold their calls for review or block them, refile one of their calls instead.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/contacts/unapprove" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100"}'

POST /v1/contacts/appear-unknown

Screen a contact like a stranger for a while

Operation

set_appear_unknown

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

For the next hours, this contact is screened like an unknown caller instead of ringing straight through. hours 0 ends it now.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/contacts/appear-unknown" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100","hours":0}'

PATCH /v1/contacts/preferences

Change one contact's preferences

Operation

update_contact_preferences

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

Per-contact options for a saved contact. record_always records every call with this contact (a recording notice plays first; available on accounts in the preview). answer_mode personal_ai lets Foyer answer this contact with a personal greeting and script instead of ringing straight through (direct). Send only the fields to change. Some of these depend on the member's plan.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PATCH "https://api.hifoyer.com/v1/contacts/preferences" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100"}'

GET /v1/remembered-callers

Callers Foyer remembers

Operation

list_remembered_callers

Auth

API key with contacts:read

People who are not contacts but have called before and gave a name; Foyer greets them by it next time. Up to 200, most recent first.

Returns

200 The remembered callers.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/remembered-callers" \
  -H "Authorization: Bearer $FOYER_API_KEY"

PATCH /v1/remembered-callers/{id}

Correct a remembered caller's name

Operation

rename_remembered_caller

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

The name Foyer greets this caller by. 1-3 words of letters, up to 40 characters.

Parameters

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PATCH "https://api.hifoyer.com/v1/remembered-callers/ID" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dave"}'

DELETE /v1/remembered-callers/{id}

Forget a remembered caller

Operation

forget_remembered_caller

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

forget=name forgets only the name; forget=all (default) forgets the caller entirely.

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X DELETE "https://api.hifoyer.com/v1/remembered-callers/ID" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/answering-profiles

Saved personal greetings

Operation

list_answering_profiles

Auth

API key with contacts:read

Reusable greetings and scripts the member saved for answering particular contacts.

Returns

200 The saved greetings.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/answering-profiles" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/answering-profiles

Save a personal greeting

Operation

save_answering_profile

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

Saves a reusable greeting and/or script. At least one of greeting, script or voice_id is required.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/answering-profiles" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /v1/answering-profiles/{id}

Remove a saved personal greeting

Operation

delete_answering_profile

Auth

API key with contacts:write

Plan

Concierge or Chief of Staff (changes data)

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X DELETE "https://api.hifoyer.com/v1/answering-profiles/ID" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/account

The member's name, plan and Foyer number

Operation

get_account

Auth

API key with settings:read

Names (and the name callers hear), pronouns, the Foyer number calls are forwarded to, and the plan with its API access.

Returns

200 The account.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/account" \
  -H "Authorization: Bearer $FOYER_API_KEY"

PATCH /v1/account/profile

Change the member's name

Operation

update_account_name

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

First, last and preferred name. The preferred name (or first and last) is what Foyer tells callers it answers for. At least one name is required; pronouns is optional.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PATCH "https://api.hifoyer.com/v1/account/profile" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

PUT /v1/account/pronouns

How Foyer refers to the member

Operation

set_pronouns

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/account/pronouns" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pronouns":"he"}'

GET /v1/settings

All settings

Operation

get_settings

Auth

API key with settings:read

Screening level and host, the greeting callers hear, recording, ringing, spam handling and notifications, grouped as in the app.

Returns

200 The settings.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/settings" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/settings/openings

Greeting choices

Operation

list_openings

Auth

API key with settings:read

The preset opening lines callers can hear (with how each sounds for this member) and the current choice. Use a preset key with PUT /v1/settings/opening.

Returns

200 The information as the Foyer app shows it.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/settings/openings" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/settings/screening-hosts

AI models that can screen calls

Operation

list_screening_hosts

Auth

API key with settings:read

The screening hosts (AI models) available on this account, which one is in use, and whether an administrator locked the choice.

Returns

200 The information as the Foyer app shows it.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/settings/screening-hosts" \
  -H "Authorization: Bearer $FOYER_API_KEY"

GET /v1/voices

Voices Foyer can speak in

Operation

list_voices

Auth

API key with settings:read

The voices available for answering calls and the current one. Use an id with PUT /v1/settings/voice.

Returns

200 The voices.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/voices" \
  -H "Authorization: Bearer $FOYER_API_KEY"

PUT /v1/settings/screening-level

How strict screening is

Operation

set_screening_level

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Send level on the 1-5 scale (1-2 lenient, 3 balanced, 4-5 strict) or level_3 on the three-level scale (1 Open, 2 Balanced, 3 Strict; stored as 1, 3 and 5). GET /v1/settings says which scale the member sees (screening.level_scale).

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/screening-level" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

PUT /v1/settings/screening-host

Which AI model screens calls

Operation

set_screening_host

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/screening-host" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host":"qwen"}'

PUT /v1/settings/opening

The first thing callers hear

Operation

set_opening

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

A preset (classic, warm, concise, butler) or custom with your own text (1-8000 characters). Foyer adds the recording notice when one is required.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/opening" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"classic"}'

PUT /v1/settings/identity-style

How much Foyer says about who it answers for

Operation

set_identity_style

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

friendly uses the member's name, balanced is more reserved, anonymous never says who it answers for.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/identity-style" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"style":"friendly"}'

PUT /v1/settings/recording

Which calls are recorded

Operation

set_recording

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

The call outcomes whose calls are recorded. Send the full list; an empty list records none. known (saved contacts) is only available on lines that support it.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/recording" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"record_outcomes":["known"]}'

PATCH /v1/settings/known-callers

Options for calls from saved contacts

Operation

set_known_caller_options

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

transcription_enabled records and transcribes calls with saved contacts (where available). greeting_enabled plays a short greeting before putting a contact through. Send one or both.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PATCH "https://api.hifoyer.com/v1/settings/known-callers" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH /v1/settings/notifications

Email and push notifications

Operation

update_notifications

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

A partial update merged into the member's notification choices, for example {"categories": {"voicemail": {"push": false}}}. Categories: voicemail, call.known, call.connect, call.review, call.voicemail_tier, call.spam, call.live, recordings, daily_digest, product_updates; each has email and/or push (see notifications.channels_available in GET /v1/settings). channels are master switches; options include voicemail_include_transcript, voicemail_include_audio_link and live_note_include_words. Unknown keys are refused.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PATCH "https://api.hifoyer.com/v1/settings/notifications" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

PUT /v1/settings/live-call-alerts

Alerts while a call is being screened

Operation

set_live_call_alerts

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/live-call-alerts" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"off"}'

PUT /v1/settings/app-badge

What the app icon badge counts

Operation

set_app_badge

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/app-badge" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"voicemail"}'

PUT /v1/settings/announcements

Push notifications for Foyer announcements

Operation

set_announcement_push

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/announcements" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"push_enabled":true}'

PUT /v1/settings/pause

Pause screening

Operation

pause_screening

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

While paused, every call rings straight through without screening (for example while expecting a verification call). indefinite stays paused until resumed; Foyer reminds the member daily.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/pause" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset":"10m"}'

DELETE /v1/settings/pause

Resume screening now

Operation

resume_screening

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X DELETE "https://api.hifoyer.com/v1/settings/pause" \
  -H "Authorization: Bearer $FOYER_API_KEY"

PUT /v1/settings/safe-word

The safe word

Operation

set_safe_word

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

A word or short phrase (up to 60 characters) that lets any caller who says it straight through without screening. Pick something only real contacts would know. An empty string clears it.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/safe-word" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"word":"example"}'

PUT /v1/settings/voice

The voice Foyer answers in

Operation

set_voice

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/voice" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id":"example"}'

PUT /v1/settings/voice-speed

How fast Foyer speaks

Operation

set_voice_speed

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/voice-speed" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"speed":0.6}'

PUT /v1/settings/ringing

Where approved calls ring

Operation

set_ringing

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

both (the Foyer app and a SIP phone), app, groundwire (SIP phone only) or none.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/ringing" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"both"}'

PUT /v1/settings/browser-ringing

Ring the web dashboard too

Operation

set_browser_ringing

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/browser-ringing" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

PUT /v1/settings/caller-name-lookup

Look up caller ID names

Operation

set_caller_name_lookup

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/caller-name-lookup" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

PUT /v1/settings/spam-auto-report

Report spam calls automatically

Operation

set_spam_auto_report

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

On some accounts this is always on and the stored choice is ignored; the response says the value in effect.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/spam-auto-report" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

PUT /v1/settings/do-not-call

Record that the number is on the Do Not Call registry

Operation

set_do_not_call

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

The member's own statement that their number is registered at donotcall.gov. Foyer cannot check the registry.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/settings/do-not-call" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"registered":true}'

GET /v1/numbers

Foyer number and forwarding lines

Operation

list_numbers

Auth

API key with settings:read

The Foyer number calls are forwarded to; the member's phone lines that forward to it, each with whether forwarding is working (forwarding_status: verified, not_forwarding or unchecked) and how to turn it on or off with that carrier; and any extra numbers that ring when a call is put through.

Returns

200 The numbers.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/numbers" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/numbers/forwarding-lines

Add a phone line that forwards to Foyer

Operation

add_forwarding_line

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Records a line the member forwards to their Foyer number. Turning forwarding on happens with the carrier; GET /v1/numbers shows the code to dial.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/numbers/forwarding-lines" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100"}'

PATCH /v1/numbers/forwarding-lines/label

Rename a forwarding line

Operation

rename_forwarding_line

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PATCH "https://api.hifoyer.com/v1/numbers/forwarding-lines/label" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100","label":"example"}'

POST /v1/numbers/forwarding-lines/remove

Remove a forwarding line from Foyer

Operation

remove_forwarding_line

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Removes the line from the member's account. It does not turn off forwarding at the carrier; calls already forwarded still reach Foyer.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/numbers/forwarding-lines/remove" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100"}'

PUT /v1/numbers/carrier

Set a line's carrier

Operation

set_line_carrier

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

The carrier of the member's primary line (or number when given), so Foyer can show the right forwarding codes.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/numbers/carrier" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"carrier":"example"}'

PUT /v1/numbers/screened-carrier

Set the carrier of an extra screened number

Operation

set_screened_number_carrier

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/numbers/screened-carrier" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100","carrier":"verizon"}'

PUT /v1/numbers/ring-destination

Ring an extra verified number

Operation

set_ring_destination

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Turns ringing on or off for a separately verified number that is not a forwarding line.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/numbers/ring-destination" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+16175550100","enabled":true}'

PUT /v1/numbers/ring-order

The order extra numbers ring in

Operation

set_ring_order

Auth

API key with settings:write

Plan

Concierge or Chief of Staff (changes data)

Numbers first to last. Only verified, enabled ring destinations are ordered; others are skipped. Depends on the plan.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/numbers/ring-order" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+16175550100"]}'

GET /v1/notes

Notes for the host and what it understands

Operation

list_notes

Auth

API key with settings:read

The member's notes to their host (the AI screener), for example "My plumber Dave will call this week, put him through", and directives, the host's working summary of all of them.

Returns

200 The notes.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/notes" \
  -H "Authorization: Bearer $FOYER_API_KEY"

POST /v1/notes

Tell the host something

Operation

add_note

Auth

API key with notes:write

Plan

Concierge or Chief of Staff (changes data)

Adds a note (3-2000 characters) the host takes into account on future calls. The response includes the host's reply and its updated directives.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/notes" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"My plumber Dave will call this week. Put him through."}'

DELETE /v1/notes/{id}

Remove a note

Operation

remove_note

Auth

API key with notes:write

Plan

Concierge or Chief of Staff (changes data)

Archives the note and recompiles the host's directives without it.

Parameters

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X DELETE "https://api.hifoyer.com/v1/notes/ID" \
  -H "Authorization: Bearer $FOYER_API_KEY"

PUT /v1/notes/directives

Edit the host's directives directly

Operation

set_directives

Auth

API key with notes:write

Plan

Concierge or Chief of Staff (changes data)

Replaces the compiled directives with this text as written. The next added or removed note recompiles over it.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/notes/directives" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"directives":"example"}'

GET /v1/profile

Facts the host knows about the member

Operation

get_host_profile

Auth

API key with settings:read

The facts the host uses when screening (family, pets, providers, vendors the member expects, where they live and work), including suggestions it learned from calls that wait for the member's decision, and whether call learning is on.

Returns

200 The information as the Foyer app shows it.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.

curl "https://api.hifoyer.com/v1/profile" \
  -H "Authorization: Bearer $FOYER_API_KEY"

PATCH /v1/profile/short-form

Edit the member's key facts

Operation

update_host_facts

Auth

API key with notes:write

Plan

Concierge or Chief of Staff (changes data)

Keys present are replaced; missing keys are left alone; empty values clear. List keys (arrays of short strings): spouse, wife, mother, father, children, pets, expectedVendors, activities. Text keys: location, industry, work.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PATCH "https://api.hifoyer.com/v1/profile/short-form" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"facts":{}}'

POST /v1/profile/facts/{id}/decision

Accept, edit or drop a fact

Operation

decide_host_fact

Auth

API key with notes:write

Plan

Concierge or Chief of Staff (changes data)

accept a suggested fact, edit it (send value), archive it, reject a suggestion, or delete a fact.

Parameters

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X POST "https://api.hifoyer.com/v1/profile/facts/ID/decision" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"accept"}'

PUT /v1/profile/learning

Let the host learn from calls

Operation

set_call_learning

Auth

API key with notes:write

Plan

Concierge or Chief of Staff (changes data)

When on (and available on the member's line), the host suggests facts from calls. Turning it off stops using learned facts right away.

Request body (JSON)

Returns

200 Done. data is what Foyer saved, in the same shape the Foyer app receives (field names may be camelCase). Re-read the resource for the API's own shape.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 402 This feature is not included in the member's plan (plan_required).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 404 No such call, contact or item on this account (not_found, media_not_found).
• 409 The change conflicts with the account's current state (conflict, key_limit).
• 429 Too many requests (rate_limited). Wait the number of seconds in Retry-After.
• 500 Something failed on Foyer's side (server_error, unavailable). Safe to retry later.

curl -X PUT "https://api.hifoyer.com/v1/profile/learning" \
  -H "Authorization: Bearer $FOYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

GET /v1/keys

The member's API keys

Operation

list_api_keys

Auth

The member's signed-in Foyer app or dashboard (not an API key)

Every key the member made, newest first, with its status. Never shows the secret. Needs the member's signed-in app session.

Returns

200 The keys.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).

curl "https://api.hifoyer.com/v1/keys" \
  -H "Authorization: Bearer $FOYER_APP_SESSION"

POST /v1/keys

Make an API key

Operation

create_api_key

Auth

The member's signed-in Foyer app or dashboard (not an API key)

Makes a key with the chosen scopes. The secret is in this response only; Foyer stores just a fingerprint of it. Write scopes need a plan that includes changes (403 plan_does_not_include_writes otherwise). At most 10 active keys.

Request body (JSON)

Returns

201 The new key, with its secret (shown once).

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).
• 403 Not allowed. insufficient_scope: the key lacks the scope named in details.required_scope. plan_does_not_include_writes: the member's plan reads only, nothing was changed. api_not_enabled: the API is not open on this account yet. forbidden: the app itself refuses this change (for example a feature not available on this line).
• 409 The change conflicts with the account's current state (conflict, key_limit).

curl -X POST "https://api.hifoyer.com/v1/keys" \
  -H "Authorization: Bearer $FOYER_APP_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dave","scopes":["calls:read"]}'

POST /v1/keys/{id}/revoke

Revoke an API key

Operation

revoke_api_key

Auth

The member's signed-in Foyer app or dashboard (not an API key)

The key stops working immediately, including audio links it made. Idempotent.

Parameters

Returns

200 The revoked key.

Errors

• 401 No valid key, or the key was revoked or expired (unauthorized).
• 404 No such call, contact or item on this account (not_found, media_not_found).

curl -X POST "https://api.hifoyer.com/v1/keys/ID/revoke" \
  -H "Authorization: Bearer $FOYER_APP_SESSION"

GET /v1/keys/activity

What each key did

Operation

get_api_activity

Auth

The member's signed-in Foyer app or dashboard (not an API key)

For each key, requests in the last days and what they read or changed in plain words ("read 14 calls, 3 voicemails, searched twice"), plus the 50 most recent requests. The log records endpoints, counts and status only, never content.

Parameters

Returns

200 The activity.

Errors

• 400 The request is missing something or has a value Foyer does not accept (invalid_request).
• 401 No valid key, or the key was revoked or expired (unauthorized).

curl "https://api.hifoyer.com/v1/keys/activity" \
  -H "Authorization: Bearer $FOYER_APP_SESSION"