Foyer Client Portal API Reference

Introduction

The Foyer API is a RESTful API, providing an interface for interacting with your Foyer client portal. REST (Representational State Transfer) uses standard HTTP methods to access and manipulate resources, allowing you to create, read, update, and delete resources like clients, files, groups and more via HTTP requests.

With the Foyer Client Portal API, you can control most aspects of your client portal. You can add or remove user, read and send encrypted messages from Spaces, upload and download files, and more.

This documentation will guide you through the various endpoints and functionalities available in the Client Portal API, to help you to programmatically manage your client portal.

Finding your API URL

Your API URL will vary depending on which region you've selected for data residency. Select the region you're using below to view the corresponding API URL.

API URL

Authentication

To use the Foyer API, you need to authenticate your requests with an API key. You can create and manage your API keys on the "Org" page using an administrator Foyer account.

Once you have your API key, you must include it in the header of all your API requests using a basic authorization header. The API Key must be set to the username value (the basic authorization password value should be empty).

It's important to keep your API keys secure. Avoid storing your secret keys in publicly accessible places such as source control or in client side code. Instead, you should use secret management services such as Azure Key Vault and perform regular rotations.

All API requests to Foyer must be made over HTTPS to ensure requests are secure in-transit. Requests made over HTTP or without proper authentication will fail.

Authenticated Request

API Key

You will need to replace the API key template API_KEY above with your own.

API keys can be generated on the "Org" page using an administrator account.

Users

In Foyer, there are three types of users: clients, staff, and admins.

Clients can visit your portal to interact in spaces, read Foyer Pages, and submit forms. They cannot create spaces and have limited access, typically read-only, except for sharing files and sending messages.

Staff can create spaces, define new forms, create Foyer Pages, and perform other tasks necessary to run your business. However, they cannot manage the Foyer organization itself.

Admins have full control over your Foyer portal. They can do everything that staff can do and more, including managing the organization settings like setting org colors, changing the org name, setting up billing, and creating API keys.

Endpoints

The Users Object

Attributes

string

The unique identifier for this object.

role

enum

The user type this user is. 1 for a client, 2 for a staff, and 3 for an admin.

string

The email address associated with the account (used for authentication and email notifications).

first_name

string

The User's first name (can be null if not set).

last_name

string

The User's last name (can be null if not set).

phone_number

string

The User phone number (can be null if not set).

avatar

string

The profile picture used for this User (can be null if not set).

created_at

string

The datetime that the User's account was created.

updated_at

string

The datetime that the User's account was last edited.

The Users Object

Create a Client

Parameters

string

The email address associated with the account (used for authentication and email notifications).

first_name

string

The User's first name (can be null if not set).

last_name

string

The User's last name (can be null if not set).

phone_number

string

The User phone number (can be null if not set).

avatar

string

The profile picture used for this User (can be null if not set).

Returns

A User object.

POST /v1/users

Response

Create a Staff

Parameters

string

The email address associated with the account (used for authentication and email notifications).

first_name

string

The User's first name (can be null if not set).

last_name

string

The User's last name (can be null if not set).

phone_number

string

The User phone number (can be null if not set).

avatar

string

The profile picture used for this User (can be null if not set).

Returns

A User object.

POST /v1/users

Response

Create an Admin

Parameters

string

The email address associated with the account (used for authentication and email notifications).

first_name

string

The User's first name (can be null if not set).

last_name

string

The User's last name (can be null if not set).

phone_number

string

The User phone number (can be null if not set).

avatar

string

The profile picture used for this User (can be null if not set).

Returns

A User object.

POST /v1/users

Response

Search for Users

Parameters

page_size

number

The number of items to return (must be between 1 and 100).

page_number

number

The page offset to apply to the query (will skip (page_number - 1) * page_size items).

query

number

The query (searches all searchable fields on the object).

order_by

Array<Order>

How the results should be ordered. The Order object has two properties id for specifying the name of the field to order by and dir to specify the direction (either desc or asc).

Returns

count

number

The total count of object that match this search (even those who are not returned).

results

Array<User>

An Array of User objects that are the results of your search.

POST /v1/users/search

Response

Retrieve a User

Returns

A User object.

GET /v1/users/:id

Response

Update a User

Parameters

string

The email address associated with the account (used for authentication and email notifications).

first_name

string

The User's first name (can be null if not set).

last_name

string

The User's last name (can be null if not set).

phone_number

string

The User phone number (can be null if not set).

avatar

string

The profile picture used for this User (can be null if not set).

Returns

A User object.

PATCH /v1/users/:id

Response

Groups

In Foyer, groups are used to organize and manage users within your client portal.

Groups allow you to categorize users based on their roles or responsibilities. You can create groups for different departments, project teams, or client segments. This helps in managing access permissions, sending targeted communications, and organizing Spaces.

Groups streamline the administration of users, making it easier to control who has access to specific resources and features within your Foyer portal.

Endpoints

The Groups Object

Attributes

string

The unique identifier for this object.

name

string

The name of the group.

users

Array<string>

An array of User object ids who are in the group.

avatar

string

The profile image for the group.

created_at

string

The datetime that the Group was created.

updated_at

string

The datetime that the Group was last edited.

The Groups Object

Create a Group

Parameters

name

string

The name of the group.

users

Array<string>

An array of User object ids who are in the group.

avatar

string

The profile image for the group.

Returns

A Group object.

POST /v1/groups

Response

Search for Groups

Parameters

page_size

number

The number of items to return (must be between 1 and 100).

page_number

number

The page offset to apply to the query (will skip (page_number - 1) * page_size items).

query

number

The query (searches all searchable fields on the object).

order_by

Array<Order>

How the results should be ordered. The Order object has two properties id for specifying the name of the field to order by and dir to specify the direction (either desc or asc).

Returns

count

number

The total count of object that match this search (even those who are not returned).

results

Array<Group>

An Array of Group objects that are the results of your search.

POST /v1/groups/search

Response

Retrieve a Group

Returns

A Group object.

GET /v1/groups/:id

Response

Update a Group

Parameters

name

string

The name of the group.

users

Array<string>

An array of User object ids who are in the group.

avatar

string

The profile image for the group.

Returns

A Group object.

PATCH /v1/groups/:id

Response

Spaces

Spaces are secure areas designed for file sharing and messaging.

Spaces allow you to create designated areas where users and groups within your organization can collaborate securely. These spaces can include any users or groups as members.

Endpoints

The Space Object

Attributes

string

The unique identifier for this object.

name

string

The name of the Space.

members

Array<string>

An object containing two fields: users and groups. users is an array of User object ids who are included as members of the Space. groups is an array of Group object ids who are included as members of the Space.

created_at

string

The datetime that the Space was created.

updated_at

string

The datetime that the Space was last edited.

The Space Object

Create a Space

Parameters

name

string

The name of the Space.

members

Array<string>

Returns

A Space object.

POST /v1/spaces

Response

Search for Spaces

Parameters

page_size

number

The number of items to return (must be between 1 and 100).

page_number

number

The page offset to apply to the query (will skip (page_number - 1) * page_size items).

query

number

The query (searches all searchable fields on the object).

order_by

Array<Order>

How the results should be ordered. The Order object has two properties id for specifying the name of the field to order by and dir to specify the direction (either desc or asc).

Returns

count

number

The total count of object that match this search (even those who are not returned).

results

Array<Space>

An Array of Space objects that are the results of your search.

POST /v1/spaces/search

Response

Retrieve a Space

Returns

A Space object.

GET /v1/spaces/:id

Response

Update a Space

Parameters

name

string

The name of the Space.

members

Array<string>

Returns

A Space object.

PATCH /v1/spaces/:id

Response

Get Space SAS Token

To perform any file operations such as uploading, downloading, deleting or updating, you'll need to get a SAS token for a file first.

SAS Tokens provided by the Foyer Client Portal API are useable for 10 minutes, and need to be refreshed regularily. This is to prevent data leaks in the event that a token is stolen. SAS Tokens generated from this endpoint are only for one individual Space.

In addition, SAS Tokens provided by the Foyer Client Portal API do not have LIST permissions so files must be searched through the Files API.

For details on how to use a SAS Token, please refer to Azure Blob Storage's API documentation.

Returns

token

string

A SAS token for this Space's Azure Blob Storage container.

url

string

A URL to this Space's container in Azure Blob Storage, with the SAS Token included as a search parameter.

GET /v1/spaces/:id

Response

Files

Files are essential for secure sharing and collaboration within spaces. Each file is associated with a specific space and can be organized within folders.

These files can include documents, images, and other types of data, each with a defined size and name. Foyer records the creator of each file and the date of creation.

Files may also include thumbnails for easy identification and can contain comments for additional context. They support versioning, allowing users to keep track of changes and updates.

In spaces, files facilitate collaboration by enabling members to share and manage documents efficiently. Similarly, when clients submit forms, they can attach relevant files.

Endpoints

The File Object

Attributes

string

The unique identifier for this object.

space_id

string

The unique identifier of the Space this file is in.

parent_id

string

The unique identifier of the parent folder (if it exists).

user_id

string

The user who uploaded this file.

name

string

The name of the file.

size

number

The size (in bytes) of the file.

is_folder

boolean

True, when this is a folder.

blob

string

A URL to Azure Blob Storage where the file is stored.

thumbnail_blob

string

A URL to Azure Blob Storage where the file's thumbnail is stored.

created_at

string

The datetime that the File was created.

The File Object

Create a File

Creating a file requires you to call get_sas for the given Space, and use Azure's Blob Storage API to upload to a new blob using that SAS token within the Space's container.

The URL to the blob (without any SAS token included) can then be included in a request to register the file with Foyer as described below.

To create folders, you can simply provide an empty blob, and set the is_folder flag to true.

Parameters

space_id

string

The unique identifier of the Space this file is in.

parent_id

string

The unique identifier of the parent folder (if it exists).

user_id

string

The user who uploaded this file.

name

string

The name of the file.

size

number

The size (in bytes) of the file.

is_folder

boolean

True, when this is a folder.

blob

string

A URL to Azure Blob Storage where the file is stored.

thumbnail_blob

string

A URL to Azure Blob Storage where the file's thumbnail is stored.

Returns

A File object.

POST /v1/spaces/:space_id/files

Response

Search for Files

Parameters

page_size

number

The number of items to return (must be between 1 and 100).

page_number

number

The page offset to apply to the query (will skip (page_number - 1) * page_size items).

query

number

The query (searches all searchable fields on the object).

order_by

Array<Order>

How the results should be ordered. The Order object has two properties id for specifying the name of the field to order by and dir to specify the direction (either desc or asc).

Returns

count

number

The total count of object that match this search (even those who are not returned).

results

Array<File>

An Array of File objects that are the results of your search.

POST /v1/spaces/:space_id/files/search

Response

Retrieve a File

Returns

A File object.

GET /v1/files/:id

Response

Messages

Messages are exchanged within spaces, providing a private and encrypted channel for users to discuss and collaborate. Each message is associated with a specific Space.

Messages can include text, file attachments, and links, allowing users to share a wide range of information quickly and easily.

Endpoints

The Message Object

Attributes

string

The unique identifier for the Message.

space_id

string

The Space this message was sent in.

user_id

string

The user who sent this message.

content

string

The text content of the message.

created_at

string

The datetime that the Message was created.

The Message Object

Send a Message

Parameters

user_id

string

The user who sent this message.

content

string

The text content of the message.

Returns

A Message object.

POST /v1/spaces/:space_id/messages

Response

Search for Messages

Parameters

page_size

number

The number of items to return (must be between 1 and 100).

page_number

number

The page offset to apply to the query (will skip (page_number - 1) * page_size items).

query

number

The query (searches all searchable fields on the object).

order_by

Array<Order>

How the results should be ordered. The Order object has two properties id for specifying the name of the field to order by and dir to specify the direction (either desc or asc).

Returns

count

number

The total count of object that match this search (even those who are not returned).

results

Array<Message>

An Array of Message objects that are the results of your search.

POST /v1/spaces/:space_id/messages/search

Response

Retrieve a Message

Returns

A Message object.

GET /v1/messages/:id

Response