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 2025-09-05
  • Added ability to edit profile crew answers in updateCompanyCrew mutation.
  • Added ability to set address when creating crew accounts with createCrew mutation.
  • Primary GraphQL API endpoint is now https://api.liveforce.co/gql (without legacy version prefix).
  • Improvements to documentation website.
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.