Skip to main content

Introduction

Liveforce public API enables you to interact with Liveforce platform programmatically, connect external automated tools and extend your workflow with various integrations. This documentation provides an overview of all available API components.

Latest changes from 2026-09-08
  • Added per-job timezones. Until now a job's times were always interpreted in its board's timezone; jobs can now carry their own IANA timezone name (e.g. Europe/London), so jobs in different regions can live on the same board with correct local times.
  • Added timezone input on the createJobs mutation. Optional — when omitted the job uses the board timezone. When set, role start / end times are interpreted in the job's timezone (including the check that a role starts on the job's date). Jobs created together as a multi-day job must all share a single timezone.
  • Added timezone input on the updateJobs mutation. Changing a job's timezone keeps the local wall-clock times of its roles unchanged and recalculates the underlying UTC times. Jobs linked in a multi-day job always share one timezone, so updating it on one linked job applies it to the whole group.
  • Extended the Job type returned by the companyJobs query with a new timezone field — the IANA timezone name the job's times are in.
  • Fixed global data types missing from crew profiles. Data types that live in a company's global sections were never returned by the companyCrewAll and companyCrewOne queries — profiles[].dataTypes only listed data types belonging to the profile itself. Attributes and skills were migrated into global sections, so their titles and crew answers were unreachable over the API even though they were populated in the app. profiles[].dataTypes now includes the global data types each profile inherits, with that crew's answer. A global data type is shared by every profile linked to its section, so the same data type id can appear under more than one profile.
  • Fixed global data types being rejected when writing crew answers. profile.dataTypes on the createCrew and updateCompanyCrew mutations resolved references only against a profile's own data types, so referencing a global one by id or uniqueId failed with an item-not-found error. Both mutations now accept global data types the profile inherits.
  • Fixed the updateProfileDataTypes mutation for global data types. It could only target data types belonging to the given profile, so uniqueId could not be assigned to a global one — leaving no stable way to address migrated attributes and skills. Global data types the profile inherits are now in scope, and the uniqueId uniqueness check covers both a profile's own and its inherited data types. Assigning a uniqueId also no longer fails validation outright.
  • Added SCORING to the DTType enum used by profiles[].dataTypes. Scoring data types were already returned by the companyCrewAll and companyCrewOne queries, but the type was missing from the published schema.
  • Fixed the status code returned when a request carries no access token. Calls to the GraphQL and REST APIs made without an Authorization header came back as 400 Bad Request, while a request carrying an expired or otherwise invalid token came back as 401 Unauthorized — the same authentication failure reported under two different codes. A missing token now returns 401 Unauthorized as well, along with a WWW-Authenticate: Bearer challenge header. The response body is unchanged ({"message":"JWT is missing."}), so only the status code and the new header differ.
Read more

Getting Started​

To use the API, your company's Liveforce account must be on payment plan that includes API access. Refer to the pricing page for more details.

Authentication​

Liveforce API uses OAuth 2.0 for authentication. Every request to the API must include a valid access token in the Authorization header. Token is generated through the OAuth 2.0 client_credentials flow. For this, you need to create an OAuth 2 client (also known as an "API Key") in the admin web app.

Go to Menu > Platform Settings > App settings > API Keys and create a new key. This will provide you with a Client ID and Client Secret. Note that this setting is only accessible to admins with Owner role or ALLOW DEVELOPER ACCESS permission.

When editing the API Key, you will be presented with selection of Scopes. Scopes define the level of access the API Key has to company's data. You should only enable scopes that are necessary for your integration. For example, if you only need to read some data, you can enable the corresponding read scope. Required scopes are listed in the documentation for each API endpoint/method.

Acquiring an access token is done by making a POST request to the following endpoint:

https://auth.liveforce.co/realms/liveforce/protocol/openid-connect/token

The request follows the OAuth 2.0 client credentials flow specification. Here's an example of how to do this using curl:

curl --request POST \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  "https://auth.liveforce.co/realms/liveforce/protocol/openid-connect/token"

Make sure to replace CLIENT_ID and CLIENT_SECRET with your actual credentials.

The response will look like this:

{
  "access_token": "eyJhbGckkOiJSUzI1NiIsInRfcCI6IkpXVCIsImtpZCI6IkxvZjZpRm...",
  "expires_in": 43200,
  "token_type": "Bearer",
  ...
}

Access tokens are short-lived and expire after a certain period (currently 12 hours). You will need to obtain a new token when the current one expires. The response includes an expires_in field indicating the lifetime of the token in seconds.

Important

Client Secret Security: Keep your Client Secret secure and do not expose it in client-side code or public repositories. It should only be used in server-side applications or secure environments. Same rules apply to the access token.

If you suspect that your Client Secret has been compromised, immediately revoke the API Key in the admin web app using RESET SECRET button in the API Key settings. This will invalidate the old secret and generate a new one.

To use the access token in your API requests, include it in the Authorization HTTP header as follows:

Authorization: Bearer YOUR_ACCESS_TOKEN

Here's an example of API request using curl:

curl --request GET \
  --url https://api.liveforce.co/[api-endpoint] \
  --header 'Authorization: Bearer eyJhbGckkOiJSUzI1NiIsInRfcCI6IkpXVCIsImtpZCI6IkxvZjZpRm...'

API Components​

  • GraphQL API is the primary API for accessing and manipulating data on Liveforce platform.

  • REST API provides additional endpoints. Some REST endpoints duplicate functionality available in GraphQL API, however it is recommended to use GraphQL API whenever possible. Certain operations (e.g. file upload) are only available via REST.

  • Webhooks is an experimental feature, that allows you to receive real-time notifications about specific events happening on Liveforce platform.

Glossary​

Reference of common terms used in this documentation:

  • API Key: An API Key is a set of credentials (Client ID and Client Secret) used to authenticate and authorize access to the Liveforce API. It represents OAuth 2.0 client and is created in the admin web app.

  • ID: A unique identifier for an entity in Liveforce platform. IDs are typically represented by numeric values.

  • Unique ID: A user-defined unique identifier for an entity in Liveforce platform. Unique IDs are typically represented by string values and can be set in the admin web app or via API.

  • Board: A board is a collection of jobs and multi-day jobs, its usage depends on company's workflow. Every job or multi-day job must belong to a board.

  • Job: A job represents a separate calendar entry for a specific date, e.g. some event or its specific day (if event spans across several days). Jobs usually contain roles.

  • Multi-day Job (MDJ): A group of jobs that are part of the same general workload, e.g. a multi-day event.

  • Role: A role represents a specific position or function within a job, e.g. "Bartender", "Waiter", "Security". Roles define the requirements for crew members needed to fill them.

  • Crew Job: A crew job represents an assignment of a crew member to a specific role within a job. It contains information about the crew member, role, status of the assignment, attendance, etc. Roles that require multiple crew members will have multiple crew jobs.