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.
- Introduced ObjectIDs, the new preferred identifier system. Old IDs keep working, but will be deprecated in the future.
- Every existing ID field in input or result types now has an ObjectID counterpart (e.g.
boardOidnext toboardId). Newly added APIs going forward, will only include ObjectIDs. - Jobs and roles get their ObjectID when created as drafts, and keep it after publishing.
- Added aliases: custom identifiers for any object, managed with companyOidAliases, setOidAliases and deleteOidAliases.
- Every existing ID field in input or result types now has an ObjectID counterpart (e.g.
- Webhooks are out of the experimental phase, and can now be set up and managed by admins in the admin web app.
- New events: JobUpdate, JobRoleUpdate, CrewBookingUpdate and CrewStatusUpdate.
- Payloads now include
event_id(the same for every retry of an event) anddelivery_timestamp. Event data now includes ObjectIDs (with the same format as in GraphQL). - Requests are signed with Ed25519 or RSA keys configured in the admin web app. Legacy HMAC SHA256 signing has been removed: webhooks that used it are sent unsigned until signing is configured again.
- Companies with API access can now invite developers under Custom admin role with Allow Developer Access permission. Such accounts can only access API and Webhooks configuration pages, and do not take up an admin seat.
- Added payment data queries: paymentReports, paymentReportItems and crewInvoices.
- Added role creation, update and deletion to the updateJobs mutation (
rolesCreate,rolesUpdate,rolesDelete). - Added
labels,imageandcoordinatesinputs to the createJobs and updateJobs mutations, and acoordinatesfield toJob. - Added crew note management to the updateCompanyCrew mutation (
notesCreate,notesUpdate,notesDelete), and anotesfield toCompanyCrewreturned by companyCrewOne. Thealertsfield is deprecated in favour ofnotes. - Added a board filter to the companyJobs query and a crew filter to the companyCrewJobs query.
- Deprecated
Role.labelsin favour ofRole.requirements. - Removed support for legacy Auth0 access tokens. Only tokens issued for API keys, registered in the admin web app are accepted.
- Fixed
roleTypeson the updateCompanyCrew mutation silently dropping role types it did not recognise. Role type names now match ignoring case and surrounding whitespace, and mutation fails if matching role type wasn't found.
Getting Started
To use the API, your company's Liveforce account must be on a 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.
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.
-
ObjectID: New experimental identifier system, intended to supersede the existing ID and Unique ID systems in the future. Read more in ObjectID section.
-
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.
ObjectID
ObjectID (OID) is a unified identifier system introduced to provide a consistent identifier format across the API.
It bridges the gap between the draft and published states of certain entities (e.g. jobs), which previously required various workarounds: every new draft now receives an ObjectID that remains unchanged after the entity is published. Note that although the ID is identical for both the draft and published entity, some API endpoints only support published entities, so passing the ObjectID of a draft may result in an error.
ObjectIDs also provide a universal alias system for all object types, offering an alternative to the existing Unique ID system, which is currently limited to data types and crew. Aliases can be configured via the GraphQL API using the setOidAliases mutation.
ObjectID identifier is a 26-character alphanumeric string, consisting of uppercase letters and digits:
01KZXAM04D444HXJBCD0V5R6MX
Aliases are user-defined strings with a maximum length of 64 characters. They can contain letters, digits, hyphens, underscores, and periods. Aliases are case-insensitive and must be unique within the object type. Using same alias string across different object types is allowed. Aliases are validated against following regular expression:
^[a-zA-Z0-9._-]{1,64}$