API docs by Redocly

Beeline Connect API (2.0)

Download OpenAPI specification:

Connect API v2 provides 2 major improvements over Connect API v1:

  1. XML & JSON support - you can specify the format of responses by sending Accept header in request: Accept: application/xml or Accept: application/json (default). The same goes for request payloads for PATCH and POST requests, which can be send in either XML or JSON format with appropriate Content-Type header (Content-Type: application/xml or Content-Type: application/json)
  2. Leaner /workers responses for improved performance - by default listing workers returns only basic worker and engagement fields. This results in faster responses and smaller response size. If your integration requires fields that are not included by default, please refer to the documentation of following parameters of GET /workers query: includeEngagementReferences, includePersonalDetails, includeCustomFields.

Some entities are not yet supported in the v2 API - the list will be extended in future. See v1 API documentation for the list of entities supported in v1 API (XML only).

workers

List all workers by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

cursorPage.first
integer >= 1
Example: cursorPage.first=50

Cursor pagination: number of items to return in this page (similar to limit). Use together with cursorPage.after for subsequent pages when paginating forward. When cursorPage is provided, cursor-based pagination is used; do not combine with limit/page.

cursorPage.after
string
Example: cursorPage.after=cursor-token-prev

Cursor pagination: opaque cursor after which the page should begin. Use the endCursor value from the previous response. When cursorPage is provided, cursor-based pagination is used; do not combine with limit/page.

includeEngagementReferences
Array of strings (OptionalEngagementReferenceType)
Items Enum: "accountablePerson" "businessSite" "classification" "company" "costCenter" "financialDetails" "holidaySchedule" "jobApplication" "jobProfile" "jobFamily" "managerDetails" "msp" "remoteWorkAddress" "supervisoryOrganization" "supplier" "terminationReason" "workSchedule" "jobClassifications" "jobFamilyGroup"

List of additional engagement reference entities to include in response. For better performance it's advised to include only the necessary references.

includePersonalDetails
Array of strings (OptionalPersonalDetailsType)
Items Enum: "addresses" "citizenships" "emergencyContact" "gender" "nationalIds" "phoneNumbers" "talentAppDemographics"

List of additional personal details to include in response. For better performance it's advised to include only the necessary fields.

includeCustomFields
Array of strings

List of reference Ids of Worker/Engagement custom fields to include in response. For better performance it's advised to include only the necessary fields.

includeFinancialFields
Array of strings

List of reference Ids of Engagement custom fields to include in response. For better performance it's advised to include only the necessary fields.

modifiedSince
string <date-time>
Example: modifiedSince=2024-07-14T12:00:00Z

Return workers that have been modified since the provided timestamp. Must be used together with modifiedTo

modifiedTo
string <date-time>
Example: modifiedTo=2024-07-14T14:00:00Z

Return workers that have only been modified up until the provided timestamp. Must be used together with modifiedSince

startDateFrom
string <date>
Example: startDateFrom=2024-01-01

Return only workers who have any engagement with a start date on or after the provided date

startDateTo
string <date>
Example: startDateTo=2024-01-01

Return only workers who have any engagement with a start date on or before the provided date

endDateFrom
string <date>
Example: endDateFrom=2024-01-01

Return only workers who have any engagement with an end date on or after the provided date

endDateTo
string <date>
Example: endDateTo=2024-01-01

Return only workers who have any engagement with an end date on or before the provided date

beelineChangedRecordsOnly
boolean

Return only workers whose properties (including engagements) have been changed in Beeline

includeRevisionHistory
boolean

Include the revision history for returned entities

onlyPrimaryEngagement
boolean

Excludes non-primary engagements from response

personalIdentifierIncludes
string

Return only workers who have an identifier like the provided value. The following fields are considered identifiers: - Company Worker ID - Primary Email - Personal Email - Legal name

engagementStatus
Array of strings (EngagementStatus)
Items Enum: "pre_hire" "onboarding" "onboarded" "offboarding" "offboarded" "draft"

Return only engagements with matching status

workerStatus
Array of strings (WorkerStatus)
Items Enum: "ACTIVE" "INACTIVE"

Return only workers with matching status

companyWorkerIds
Array of strings

Return only workers whose company worker IDs are in the set provided

classificationReferenceIds
Array of strings

Return only workers who have any engagement with a classification matching any of the provided reference IDs

companyReferenceIds
Array of strings

Return only workers who have a company matching any of the provided reference IDs

organizationReferenceIds
Array of strings

Return only workers who have a supervisory organization matching any of the provided reference IDs

genderReferenceIds
Array of strings

Return only workers with gender matching any of the provided reference IDs

nationalIdType
string

Return only workers with national id type matching provided

nationalIdValue
string

Return only workers with national id value matching provided

dateOfBirth
string <date>
Example: dateOfBirth=1990-12-31

Filter workers by exact date of birth

filterEngagementsByClassification
boolean

When true, only engagements with classification specified by classificationReferenceIds will be present in response

Responses

Response samples

Content type
{
  • "totalCount": 9876,
  • "totalPages": 10,
  • "endCursor": "endCursorToken",
  • "workers": [
    ]
}

Create a worker

Request Body schema:
required

New worker to be created

workerId
string (WorkerId)
tenureStartDate
string <date>
object (PersonalDetailsUpdate)
Array of objects (EngagementCreate)

Responses

Request samples

Content type
{
  • "workerId": "21006",
  • "tenureStartDate": "2019-08-24",
  • "personalDetails": {
    },
  • "engagements": [
    ]
}

Response samples

Content type
{
  • "totalCount": 9876,
  • "totalPages": 10,
  • "endCursor": "endCursorToken",
  • "workers": [
    ]
}

Get Worker details by UID

path Parameters
uid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

person UID

query Parameters
includeRevisionHistory
boolean

Include the revision history for returned worker

Responses

Response samples

Content type
{
  • "uid": "P0df55682-e400-4b66-87a7-bea6a183a4c8",
  • "workerId": "21006",
  • "displayName": "John Doe",
  • "applicantId": {
    },
  • "externalIds": [
    ],
  • "tenureStartDate": "2019-08-24",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "deleted": true,
  • "personalDetails": {
    },
  • "engagements": [
    ]
}

Update worker

path Parameters
uid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

person UID

Request Body schema:
required

Worker properties to be updated

workerId
string (WorkerId)
tenureStartDate
string <date>
object (PersonalDetailsUpdate)

Responses

Request samples

Content type
{
  • "workerId": "21006",
  • "tenureStartDate": "2019-08-24",
  • "personalDetails": {
    }
}

Response samples

Content type
{
  • "uid": "P0df55682-e400-4b66-87a7-bea6a183a4c8",
  • "workerId": "21006",
  • "displayName": "John Doe",
  • "applicantId": {
    },
  • "externalIds": [
    ],
  • "tenureStartDate": "2019-08-24",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "deleted": true,
  • "personalDetails": {
    },
  • "engagements": [
    ]
}

Get engagement details

path Parameters
workerUid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

worker UID

engagementUid
required
string
Example: E0df55682-e400-4b66-87a7-bea6a183a4c8

engagement UID

Responses

Response samples

Content type
{
  • "uid": "E24b5e384-6ee2-4452-9fb0-77033e7ce6ca",
  • "engagementId": "00000000-0001",
  • "primary": true,
  • "title": "Specialist",
  • "status": "pre_hire",
  • "externalStatus": {
    },
  • "originalStartDate": "2019-08-24",
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "offboardOnEndDate": true,
  • "customFields": [
    ],
  • "financialFields": [
    ],
  • "poNumber": "string",
  • "workEmail": "someone@some.company",
  • "workPhones": [
    ],
  • "isManager": true,
  • "workLocationType": "on_site",
  • "workCity": "string",
  • "workProvince": "string",
  • "appendixRequest": {
    },
  • "badgeId": "string",
  • "accountablePerson": {
    },
  • "holidaySchedule": {
    },
  • "workSchedule": {
    },
  • "jobApplication": {
    },
  • "jobProfile": {
    },
  • "jobFamily": {
    },
  • "managerDetails": {
    },
  • "msp": {
    },
  • "classification": {
    },
  • "supervisoryOrganization": {
    },
  • "company": {
    },
  • "costCenters": [
    ],
  • "businessSite": {
    },
  • "supplier": {
    },
  • "terminationReason": {
    },
  • "remoteWorkAddress": {
    },
  • "financialDetails": {
    },
  • "revisions": [
    ]
}

Update worker's engagement

path Parameters
workerUid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

worker UID

engagementUid
required
string
Example: E0df55682-e400-4b66-87a7-bea6a183a4c8

engagement UID

Request Body schema:
required

Engagement properties to be updated

primary
boolean
title
string
status
string (EngagementStatus)
Enum: "pre_hire" "onboarding" "onboarded" "offboarding" "offboarded" "draft"
originalStartDate
string <date>
startDate
string <date>
endDate
string <date>
offboardOnEndDate
boolean
Array of objects (CustomFieldPatchValue)
Array of objects (FinancialFieldPatchValue)
poNumber
string
workEmail
string <email>
Array of objects (PhoneNumber)
workLocationType
string (WorkLocationType)
Enum: "on_site" "remote"
workCity
string
workProvince
string
object (EngagementAppendixRequest)
badgeId
string
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
Array of objects (CostCenterReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (EngagementRemoteWorkAddressUpdate)
object (EngagementFinancialDetailsUpdate)

Responses

Request samples

Content type
{
  • "primary": true,
  • "title": "Specialist",
  • "status": "pre_hire",
  • "originalStartDate": "2019-08-24",
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "offboardOnEndDate": true,
  • "customFields": [
    ],
  • "financialFields": [
    ],
  • "poNumber": "string",
  • "workEmail": "someone@some.company",
  • "workPhones": [
    ],
  • "workLocationType": "on_site",
  • "workCity": "string",
  • "workProvince": "string",
  • "appendixRequest": {
    },
  • "badgeId": "string",
  • "accountablePerson": {
    },
  • "holidaySchedule": {
    },
  • "workSchedule": {
    },
  • "jobApplication": {
    },
  • "jobProfile": {
    },
  • "jobFamily": {
    },
  • "msp": {
    },
  • "classification": {
    },
  • "supervisoryOrganization": {
    },
  • "company": {
    },
  • "costCenters": [
    ],
  • "businessSite": {
    },
  • "supplier": {
    },
  • "terminationReason": {
    },
  • "remoteWorkAddress": {
    },
  • "financialDetails": {
    }
}

Response samples

Content type
{
  • "uid": "E24b5e384-6ee2-4452-9fb0-77033e7ce6ca",
  • "engagementId": "00000000-0001",
  • "primary": true,
  • "title": "Specialist",
  • "status": "pre_hire",
  • "externalStatus": {
    },
  • "originalStartDate": "2019-08-24",
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "offboardOnEndDate": true,
  • "customFields": [
    ],
  • "financialFields": [
    ],
  • "poNumber": "string",
  • "workEmail": "someone@some.company",
  • "workPhones": [
    ],
  • "isManager": true,
  • "workLocationType": "on_site",
  • "workCity": "string",
  • "workProvince": "string",
  • "appendixRequest": {
    },
  • "badgeId": "string",
  • "accountablePerson": {
    },
  • "holidaySchedule": {
    },
  • "workSchedule": {
    },
  • "jobApplication": {
    },
  • "jobProfile": {
    },
  • "jobFamily": {
    },
  • "managerDetails": {
    },
  • "msp": {
    },
  • "classification": {
    },
  • "supervisoryOrganization": {
    },
  • "company": {
    },
  • "costCenters": [
    ],
  • "businessSite": {
    },
  • "supplier": {
    },
  • "terminationReason": {
    },
  • "remoteWorkAddress": {
    },
  • "financialDetails": {
    },
  • "revisions": [
    ]
}

Discard engagement pending changes

Discards any pending changes for an engagement and terminates the relevant processes

path Parameters
workerUid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

worker UID

engagementUid
required
string
Example: E0df55682-e400-4b66-87a7-bea6a183a4c8

engagement UID

query Parameters
reason
required
string

termination reason for the relevant processes

Responses

Response samples

Content type
{
  • "numberOfPendingChangesDiscarded": 5
}

organizations

List all organizations by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

referenceIds
Array of strings

Return only organizations whose reference IDs appear in the provided set

managerReferenceIds
Array of strings

Return only organizations whose managers company worker IDs are included in the provided set

Responses

Response samples

Content type
{
  • "totalCount": 9876,
  • "totalPages": 10,
  • "orgs": [
    ]
}

Create an organization

Request Body schema:
required

New organization to be created

referenceId
string
displayName
required
string
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)

Responses

Request samples

Content type
{
  • "referenceId": "abc_123",
  • "displayName": "Org Name",
  • "manager": {
    },
  • "parentOrg": {
    },
  • "location": {
    }
}

Response samples

Content type
{
  • "uid": "Oa11c01bc-41e1-4790-b0d8-641d9ea5982c",
  • "referenceId": "abc_123",
  • "displayName": "Org Name",
  • "manager": {
    },
  • "parentOrg": {
    },
  • "location": {
    },
  • "customFields": [
    ]
}

Get organization details by UID

path Parameters
uid
required
string
Example: Oa11c01bc-41e1-4790-b0d8-641d9ea5982c

organization UID

Responses

Response samples

Content type
{
  • "uid": "Oa11c01bc-41e1-4790-b0d8-641d9ea5982c",
  • "referenceId": "abc_123",
  • "displayName": "Org Name",
  • "manager": {
    },
  • "parentOrg": {
    },
  • "location": {
    },
  • "customFields": [
    ]
}

Update an organization

path Parameters
uid
required
string
Example: Oa11c01bc-41e1-4790-b0d8-641d9ea5982c

organization UID

Request Body schema:
required

Organization properties to be updated

referenceId
string
displayName
string
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)
object (ReferenceIdOrUid)

Responses

Request samples

Content type
{
  • "referenceId": "abc_123_updated",
  • "displayName": "Org Name Updated",
  • "manager": {
    },
  • "parentOrg": {
    },
  • "location": {
    }
}

Response samples

Content type
{
  • "uid": "Oa11c01bc-41e1-4790-b0d8-641d9ea5982c",
  • "referenceId": "abc_123",
  • "displayName": "Org Name",
  • "manager": {
    },
  • "parentOrg": {
    },
  • "location": {
    },
  • "customFields": [
    ]
}

Delete an organization

path Parameters
uid
required
string
Example: Oa11c01bc-41e1-4790-b0d8-641d9ea5982c

organization UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

businessSites

List all business sites by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

referenceIds
Array of strings

Return only business sites whose reference IDs appear in the provided set

assignable
boolean

Filter entities based on whether or not they are assignable

search
string

Search for entities by displayName

Responses

Response samples

Content type
{
  • "totalCount": 9366,
  • "totalPages": 10,
  • "businessSites": [
    ]
}

Create a business site

Request Body schema:
required

New business site to be created

displayName
required
string
referenceId
string
required
object (BusinessSiteAddress)
assignable
boolean
object (ReferenceIdOrUid)

Responses

Request samples

Content type
{
  • "displayName": "London Office",
  • "referenceId": "LD-001",
  • "address": {
    },
  • "assignable": true,
  • "parent": {
    }
}

Response samples

Content type
{
  • "uid": "LCbe236abf-5a2b-4c27-9904-a5794590d88c",
  • "displayName": "London Office",
  • "referenceId": "LD-001",
  • "address": {
    },
  • "assignable": true,
  • "geolocation": {
    },
  • "parent": {
    }
}

Get business site by uid

path Parameters
uid
required
string
Example: LC51d1c513-2004-48c3-b702-cf74718ce50d

Unique ID of the businessSite

Responses

Response samples

Content type
{
  • "uid": "LCbe236abf-5a2b-4c27-9904-a5794590d88c",
  • "displayName": "London Office",
  • "referenceId": "LD-001",
  • "address": {
    },
  • "assignable": true,
  • "geolocation": {
    },
  • "parent": {
    }
}

Update a business site

path Parameters
uid
required
string
Example: LC51d1c513-2004-48c3-b702-cf74718ce50d

businessSite UID

Request Body schema:
required

Business site properties to be updated

displayName
string
referenceId
string
object (ReferenceIdOrUid)
object (BusinessSiteAddress)
assignable
boolean

Responses

Request samples

Content type
{
  • "displayName": "London Office 2",
  • "referenceId": "LD-002",
  • "parent": {
    },
  • "address": {
    },
  • "assignable": false
}

Response samples

Content type
{
  • "uid": "LCbe236abf-5a2b-4c27-9904-a5794590d88c",
  • "displayName": "London Office",
  • "referenceId": "LD-001",
  • "address": {
    },
  • "assignable": true,
  • "geolocation": {
    },
  • "parent": {
    }
}

Delete business site by uid

path Parameters
uid
required
string
Example: LC51d1c513-2004-48c3-b702-cf74718ce50d

businessSite UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

jobProfiles

List all job profiles by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

referenceIds
Array of strings

Return only job profiles whose reference IDs appear in the provided set

classificationUid
string

Filter job profiles by classification UID

jobFamilyUid
string

Filter job profiles by job family UID

countryCodes
Array of strings (CountryCode)
Example: countryCodes=US

Filter job profiles by ISO Alpha-2 country codes

uids
Array of strings

Return only job profiles whose UIDs appear in the provided set

search
string

Search for job profiles by displayName or referenceCode

Responses

Response samples

Content type
{
  • "totalCount": 250,
  • "totalPages": 13,
  • "jobProfiles": [
    ]
}

Create a job profile

Request Body schema:
required

New job profile to be created

referenceCode
required
string
displayName
required
string
referenceId
string
summary
string
description
string
assignable
boolean
countries
Array of strings (CountryCode)

List of ISO Alpha-2 country codes

Array of objects (ReferenceIdOrUid)

List of classification references (provide uid or referenceId)

object

Job family reference (provide uid or referenceId)

Array of objects (ReferenceIdOrUid)

List of job classification references (provide uid or referenceId)

object

Mapped export job profile reference (provide uid or referenceId)

Array of objects (JobProfileEligibilityRequirement)
Array of objects (CustomFieldPatchValue)

Responses

Request samples

Content type
{
  • "referenceCode": "JP-001",
  • "displayName": "Data Analyst",
  • "referenceId": "00000123",
  • "summary": "Responsible for analyzing business data and delivering insights",
  • "description": "Full job profile description here",
  • "assignable": true,
  • "countries": [
    ],
  • "classifications": [
    ],
  • "jobFamily": {
    },
  • "jobClassifications": [
    ],
  • "mappedExportJobProfile": {
    },
  • "eligibilityRequirements": [
    ],
  • "customFields": [
    ]
}

Response samples

Content type
{
  • "uid": "RObfa4eb6f-36ad-4e1b-b868-fe93e6a7a1f9",
  • "referenceId": "00000123",
  • "referenceCode": "JP-001",
  • "displayName": "Data Analyst",
  • "externalIds": [
    ],
  • "summary": "Responsible for analyzing business data and delivering insights",
  • "description": "Full job profile description here",
  • "assignable": true,
  • "countries": [
    ],
  • "classifications": [
    ],
  • "jobFamily": {
    },
  • "jobFamilyGroup": {
    },
  • "jobClassifications": [
    ],
  • "mappedExportJobProfile": {
    },
  • "eligibilityRequirements": [
    ],
  • "customFields": [
    ]
}

Get job profile by uid

path Parameters
uid
required
string
Example: RObfa4eb6f-36ad-4e1b-b868-fe93e6a7a1f9

Unique ID of the job profile

Responses

Response samples

Content type
{
  • "uid": "RObfa4eb6f-36ad-4e1b-b868-fe93e6a7a1f9",
  • "referenceId": "00000123",
  • "referenceCode": "JP-001",
  • "displayName": "Data Analyst",
  • "externalIds": [
    ],
  • "summary": "Responsible for analyzing business data and delivering insights",
  • "description": "Full job profile description here",
  • "assignable": true,
  • "countries": [
    ],
  • "classifications": [
    ],
  • "jobFamily": {
    },
  • "jobFamilyGroup": {
    },
  • "jobClassifications": [
    ],
  • "mappedExportJobProfile": {
    },
  • "eligibilityRequirements": [
    ],
  • "customFields": [
    ]
}

Update a job profile

path Parameters
uid
required
string
Example: RObfa4eb6f-36ad-4e1b-b868-fe93e6a7a1f9

job profile UID

Request Body schema:
required

Job profile properties to be updated

referenceCode
string
displayName
string
referenceId
string
summary
string
description
string
assignable
boolean
countries
Array of strings (CountryCode)

List of ISO Alpha-2 country codes

Array of objects (ReferenceIdOrUid)

List of classification references (provide uid or referenceId)

Array of objects (ReferenceIdOrUid)

List of job classification references (provide uid or referenceId)

object

Job family reference (provide uid or referenceId)

object

Mapped export job profile reference for PATCH (uid only)

Array of objects (JobProfileEligibilityRequirement)
Array of objects (CustomFieldPatchValue)

For job profile PATCH, each custom field item must include referenceId

Responses

Request samples

Content type
{
  • "referenceCode": "JP-001-updated",
  • "displayName": "Senior Data Analyst",
  • "referenceId": "00000123",
  • "summary": "Leads advanced analytics and reporting initiatives",
  • "description": "Updated description",
  • "assignable": true,
  • "countries": [
    ],
  • "classifications": [
    ],
  • "jobClassifications": [
    ],
  • "jobFamily": {
    },
  • "mappedExportJobProfile": {
    },
  • "eligibilityRequirements": [
    ],
  • "customFields": [
    ]
}

Response samples

Content type
{
  • "uid": "RObfa4eb6f-36ad-4e1b-b868-fe93e6a7a1f9",
  • "referenceId": "00000123",
  • "referenceCode": "JP-001",
  • "displayName": "Data Analyst",
  • "externalIds": [
    ],
  • "summary": "Responsible for analyzing business data and delivering insights",
  • "description": "Full job profile description here",
  • "assignable": true,
  • "countries": [
    ],
  • "classifications": [
    ],
  • "jobFamily": {
    },
  • "jobFamilyGroup": {
    },
  • "jobClassifications": [
    ],
  • "mappedExportJobProfile": {
    },
  • "eligibilityRequirements": [
    ],
  • "customFields": [
    ]
}

Delete job profile by uid

path Parameters
uid
required
string
Example: RObfa4eb6f-36ad-4e1b-b868-fe93e6a7a1f9

job profile UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

jobFamilies

List all job families by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

referenceIds
Array of strings

Return only job families whose reference IDs appear in the provided set

jobFamilyGroupUid
string

Filter job families by job family group UID

search
string

Search for entities by displayName or referenceId

Responses

Response samples

Content type
{
  • "totalCount": 120,
  • "totalPages": 6,
  • "jobFamilies": [
    ]
}

Create a job family

Request Body schema:
required

New job family to be created

referenceId
string
displayName
required
string
summary
string
object

Job family group reference (provide uid or referenceId)

Responses

Request samples

Content type
{
  • "referenceId": "JF-001",
  • "displayName": "Data and Analytics",
  • "summary": "Covers analyst and reporting-related roles",
  • "jobFamilyGroup": {
    }
}

Response samples

Content type
{
  • "uid": "JFc95392cf-9f82-3adb-841e-fcd5bfc7cb63",
  • "referenceId": "JF-001",
  • "displayName": "Data and Analytics",
  • "summary": "Covers analyst and reporting-related roles",
  • "jobFamilyGroup": {
    }
}

Get job family details by UID

path Parameters
uid
required
string
Example: JFc95392cf-9f82-3adb-841e-fcd5bfc7cb63

job family UID

Responses

Response samples

Content type
{
  • "uid": "JFc95392cf-9f82-3adb-841e-fcd5bfc7cb63",
  • "referenceId": "JF-001",
  • "displayName": "Data and Analytics",
  • "summary": "Covers analyst and reporting-related roles",
  • "jobFamilyGroup": {
    }
}

Update a job family

path Parameters
uid
required
string
Example: JFc95392cf-9f82-3adb-841e-fcd5bfc7cb63

job family UID

Request Body schema:
required

Job family properties to be updated

referenceId
string
displayName
string
summary
string
object

Job family group reference (provide uid or referenceId)

Responses

Request samples

Content type
{
  • "referenceId": "JF-001-updated",
  • "displayName": "Data and Analytics Updated",
  • "summary": "Updated job family scope",
  • "jobFamilyGroup": {
    }
}

Response samples

Content type
{
  • "uid": "JFc95392cf-9f82-3adb-841e-fcd5bfc7cb63",
  • "referenceId": "JF-001",
  • "displayName": "Data and Analytics",
  • "summary": "Covers analyst and reporting-related roles",
  • "jobFamilyGroup": {
    }
}

Delete a job family

path Parameters
uid
required
string
Example: JFc95392cf-9f82-3adb-841e-fcd5bfc7cb63

job family UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

jobFamilyGroups

List all job family groups by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

referenceIds
Array of strings

Return only job family groups whose reference IDs appear in the provided set

search
string

Search for entities by displayName or referenceId

Responses

Response samples

Content type
{
  • "totalCount": 35,
  • "totalPages": 2,
  • "jobFamilyGroups": [
    ]
}

Create a job family group

Request Body schema:
required

New job family group to be created

referenceId
string
displayName
required
string
summary
string

Responses

Request samples

Content type
{
  • "referenceId": "JFG-001",
  • "displayName": "Professional Services",
  • "summary": "Groups job families related to services delivery"
}

Response samples

Content type
{
  • "uid": "JFG4fdd396b-8820-44c0-8637-f4436797be52",
  • "referenceId": "JFG-001",
  • "displayName": "Professional Services",
  • "summary": "Groups job families related to services delivery"
}

Get job family group details by UID

path Parameters
uid
required
string
Example: JFG4fdd396b-8820-44c0-8637-f4436797be52

job family group UID

Responses

Response samples

Content type
{
  • "uid": "JFG4fdd396b-8820-44c0-8637-f4436797be52",
  • "referenceId": "JFG-001",
  • "displayName": "Professional Services",
  • "summary": "Groups job families related to services delivery"
}

Update a job family group

path Parameters
uid
required
string
Example: JFG4fdd396b-8820-44c0-8637-f4436797be52

job family group UID

Request Body schema:
required

Job family group properties to be updated

referenceId
string
displayName
string
summary
string

Responses

Request samples

Content type
{
  • "referenceId": "JFG-001-updated",
  • "displayName": "Professional Services Updated",
  • "summary": "Updated grouping for service-related job families"
}

Response samples

Content type
{
  • "uid": "JFG4fdd396b-8820-44c0-8637-f4436797be52",
  • "referenceId": "JFG-001",
  • "displayName": "Professional Services",
  • "summary": "Groups job families related to services delivery"
}

Delete a job family group

path Parameters
uid
required
string
Example: JFG4fdd396b-8820-44c0-8637-f4436797be52

job family group UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

classifications

List classifications by criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: page number, starting from 1

statuses
Array of strings (ClassificationStatus)
Items Enum: "ACTIVE" "INACTIVE"

Filter by classification statuses (ACTIVE or INACTIVE). Defaults to ACTIVE when omitted.

type
string (ClassificationType)
Enum: "EMPLOYEE" "NON_EMPLOYEE" "UNKNOWN"

Filter by classification type.

assignable
boolean

Filter by assignable flag.

jobProfileUid
string

Filter classifications related to the provided job profile UID.

forceJobProfileRelationship
boolean
Default: false

If true and jobProfileUid is provided, always enforce job-profile relationship filtering.

referenceIds
Array of strings

Return only classifications with matching reference ids.

Responses

Response samples

Content type
{
  • "totalCount": 1,
  • "totalPages": 1,
  • "classifications": [
    ]
}

Create a classification

Request Body schema:
required

New classification to be created

displayName
required
string non-empty

Classification display name.

description
string

Optional classification description.

status
string
Enum: "ACTIVE" "INACTIVE"

Defaults to ACTIVE if omitted.

type
required
string (ClassificationType)
Enum: "EMPLOYEE" "NON_EMPLOYEE" "UNKNOWN"
assignable
boolean
Default: true

Assignable flag. Defaults to true if omitted.

referenceId
string

External reference identifier. Must be unique among active classifications.

Responses

Request samples

Content type
{
  • "displayName": "Employee",
  • "description": "Assigns workers as employees",
  • "status": "ACTIVE",
  • "type": "EMPLOYEE",
  • "assignable": true,
  • "referenceId": "CLS-001"
}

Response samples

Content type
{
  • "uid": "CL51d1c513-2004-48c3-b702-cf74718ce50d",
  • "referenceId": "CLS-001",
  • "displayName": "Employee",
  • "description": "Used to group workers by employment relationship",
  • "status": "ACTIVE",
  • "type": "EMPLOYEE",
  • "assignable": true,
  • "referenceCode": "string",
  • "wid": "string",
  • "externalName": "string"
}

Get classification by uid

path Parameters
uid
required
string
Example: CL51d1c513-2004-48c3-b702-cf74718ce50d

Classification UID

Responses

Response samples

Content type
{
  • "uid": "CL51d1c513-2004-48c3-b702-cf74718ce50d",
  • "referenceId": "CLS-001",
  • "displayName": "Employee",
  • "description": "Used to group workers by employment relationship",
  • "status": "ACTIVE",
  • "type": "EMPLOYEE",
  • "assignable": true,
  • "referenceCode": "string",
  • "wid": "string",
  • "externalName": "string"
}

Patch a classification

path Parameters
uid
required
string
Example: CL51d1c513-2004-48c3-b702-cf74718ce50d

Classification UID

Request Body schema:
required

Classification properties to be updated

displayName
string non-empty
description
string non-empty
status
string
Enum: "ACTIVE" "INACTIVE"
type
string (ClassificationType)
Enum: "EMPLOYEE" "NON_EMPLOYEE" "UNKNOWN"
assignable
boolean
referenceId
string

Responses

Request samples

Content type
{
  • "displayName": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "type": "EMPLOYEE",
  • "assignable": true,
  • "referenceId": "string"
}

Response samples

Content type
{
  • "uid": "CL51d1c513-2004-48c3-b702-cf74718ce50d",
  • "referenceId": "CLS-001",
  • "displayName": "Employee",
  • "description": "Used to group workers by employment relationship",
  • "status": "ACTIVE",
  • "type": "EMPLOYEE",
  • "assignable": true,
  • "referenceCode": "string",
  • "wid": "string",
  • "externalName": "string"
}

Delete classification by uid

path Parameters
uid
required
string
Example: CL51d1c513-2004-48c3-b702-cf74718ce50d

Classification UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

companies

List all companies by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

referenceIds
Array of strings

Return only companies whose reference IDs appear in the provided set

assignable
boolean

Filter entities based on whether or not they are assignable

search
string

Search for entities by displayName

Responses

Response samples

Content type
{
  • "totalCount": 9876,
  • "totalPages": 10,
  • "companies": [
    ]
}

Create a company

Request Body schema:
required

New company to be created

referenceId
string
referenceCode
string
displayName
required
string
assignable
boolean
currency
string (Currency)

3-letter currency code

subtype
string

Responses

Request samples

Content type
{
  • "referenceId": "COMP_432",
  • "referenceCode": "beeline_company_001",
  • "displayName": "Company Name",
  • "assignable": true,
  • "currency": "USD",
  • "subtype": "Subsidiary"
}

Response samples

Content type
{
  • "uid": "CO51d1c513-2004-48c3-b702-cf74718ce50d",
  • "referenceId": "COMP_432",
  • "referenceCode": "beeline_company_001",
  • "displayName": "Company Name",
  • "assignable": true,
  • "currency": "USD",
  • "subtype": "Subsidiary"
}

Get company details by UID

path Parameters
uid
required
string
Example: CO51d1c513-2004-48c3-b702-cf74718ce50d

company UID

Responses

Response samples

Content type
{
  • "uid": "CO51d1c513-2004-48c3-b702-cf74718ce50d",
  • "referenceId": "COMP_432",
  • "referenceCode": "beeline_company_001",
  • "displayName": "Company Name",
  • "assignable": true,
  • "currency": "USD",
  • "subtype": "Subsidiary"
}

Update a company

path Parameters
uid
required
string
Example: CO51d1c513-2004-48c3-b702-cf74718ce50d

company UID

Request Body schema:
required

Company properties to be updated

referenceId
string
referenceCode
string
displayName
string
assignable
boolean
currency
string (Currency)

3-letter currency code

subtype
string

Responses

Request samples

Content type
{
  • "referenceId": "COMP_432_updated",
  • "referenceCode": "beeline_company_001",
  • "displayName": "Company Name Updated",
  • "assignable": false,
  • "currency": "USD",
  • "subtype": "Branch"
}

Response samples

Content type
{
  • "uid": "CO51d1c513-2004-48c3-b702-cf74718ce50d",
  • "referenceId": "COMP_432",
  • "referenceCode": "beeline_company_001",
  • "displayName": "Company Name",
  • "assignable": true,
  • "currency": "USD",
  • "subtype": "Subsidiary"
}

Delete a company

path Parameters
uid
required
string
Example: CO51d1c513-2004-48c3-b702-cf74718ce50d

company UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

costCenters

List all cost centers by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

referenceIds
Array of strings

Return only cost centers whose reference IDs appear in the provided set

Responses

Response samples

Content type
{
  • "totalCount": 9876,
  • "totalPages": 10,
  • "costCenters": [
    ]
}

Create a cost center

Request Body schema:
required

New cost center to be created

referenceId
string
referenceCode
required
string
displayName
required
string

Responses

Request samples

Content type
{
  • "referenceId": "a23BC_432",
  • "referenceCode": "beeline_const_center_001",
  • "displayName": "Cost Center Name"
}

Response samples

Content type
{
  • "uid": "CCa3b78f66-d71a-4930-9eb7-858df189bb20",
  • "referenceId": "a23BC_432",
  • "referenceCode": "beeline_const_center_001",
  • "displayName": "Cost Center Name"
}

Get cost center details by UID

path Parameters
uid
required
string
Example: CCa3b78f66-d71a-4930-9eb7-858df189bb20

cost center UID

Responses

Response samples

Content type
{
  • "uid": "CCa3b78f66-d71a-4930-9eb7-858df189bb20",
  • "referenceId": "a23BC_432",
  • "referenceCode": "beeline_const_center_001",
  • "displayName": "Cost Center Name"
}

Update a cost center

path Parameters
uid
required
string
Example: CCa3b78f66-d71a-4930-9eb7-858df189bb20

cost center UID

Request Body schema:
required

Cost center properties to be updated

referenceId
string
referenceCode
string
displayName
string

Responses

Request samples

Content type
{
  • "referenceId": "a23BC_432_updated",
  • "referenceCode": "beeline_const_center_001",
  • "displayName": "Cost Center Name Updated"
}

Response samples

Content type
{
  • "uid": "CCa3b78f66-d71a-4930-9eb7-858df189bb20",
  • "referenceId": "a23BC_432",
  • "referenceCode": "beeline_const_center_001",
  • "displayName": "Cost Center Name"
}

Delete a cost center

path Parameters
uid
required
string
Example: CCa3b78f66-d71a-4930-9eb7-858df189bb20

cost center UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

jobPostings

List all job postings by given criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

search
string

Search for job postings by posting UID or job profile title

statuses
Array of strings (JobPostingStatus)
Items Enum: "DRAFT" "PENDING" "IN_PROGRESS" "FILLED" "REJECTED" "CANCELLED" "DELETED"

Return only job postings with statuses in the provided set

modifiedSince
string <date-time>
Example: modifiedSince=2026-01-01T00:00:00Z

Return job postings modified since the provided timestamp. Must be used together with modifiedTo.

modifiedTo
string <date-time>
Example: modifiedTo=2026-01-31T23:59:59Z

Return job postings modified up to the provided timestamp. Must be used together with modifiedSince.

Responses

Response samples

Content type
{
  • "totalCount": 25,
  • "totalPages": 2,
  • "jobPostings": [
    ]
}

Create a job posting

Request Body schema:
required

New job posting to be created

workRequestUid
required
string

UID of the work request to which this job posting will be attached.

type
string
Enum: "JOB" "SOW"

Work posting type. When omitted by create, defaults to JOB.

requestedWorkerCount
integer >= 1
Default: 1

Number of workers requested. Must be at least 1.

object (Amount)
object (Amount)
object (Amount)
object (Amount)
billRatePeriod
string (RatePeriod)
Enum: "hourly" "daily" "weekly" "bi_weekly" "monthly" "other" "on_invoice"
paymentBasis
string (JobPostingPaymentBasis)
Enum: "TIME" "TIME_AND_MATERIALS" "SOW"
object (Amount)
object

Job profile reference. Required when type resolves to JOB.

object

Classification reference (provide uid or referenceId)

object

Supervisory organization reference (provide uid or referenceId)

object

Business site reference (provide uid or referenceId)

object

Cost center reference (provide uid or referenceId)

object

MSP reference (provide uid or referenceId)

startDate
string <date>

Start date. Required in non-draft workflow paths.

endDate
string <date>
expiryDate
string <date>
externalTitle
string
externalDescription
string
jobSummary
string
Array of objects (CustomFieldPatchValue)
Array of objects (FinancialFieldPatchValue)

Responses

Request samples

Content type
{
  • "workRequestUid": "WRf65f771a-f082-4127-9046-f6f6b2d9de4f",
  • "type": "JOB",
  • "requestedWorkerCount": 1,
  • "minimumBillRate": {
    },
  • "maximumBillRate": {
    },
  • "minimumPayRate": {
    },
  • "maximumPayRate": {
    },
  • "billRatePeriod": "hourly",
  • "paymentBasis": "TIME",
  • "projectedCost": {
    },
  • "jobProfile": {
    },
  • "classification": {
    },
  • "supervisoryOrganization": {
    },
  • "businessSite": {
    },
  • "costCenter": {
    },
  • "msp": {
    },
  • "startDate": "2026-01-01",
  • "endDate": "2026-06-30",
  • "expiryDate": "2025-12-01",
  • "externalTitle": "Data Analyst - Contract",
  • "externalDescription": "Initial posting for data analyst role",
  • "jobSummary": "6-month analytics assignment",
  • "customFields": [
    ],
  • "financialFields": [
    ]
}

Response samples

Content type
{
  • "uid": "JR20f2de7d-da92-4a72-b69c-b8f4bcecb3ed",
  • "referenceId": "1000123",
  • "requestedWorkerCount": 2,
  • "minimumBillRate": {
    },
  • "maximumBillRate": {
    },
  • "minimumPayRate": {
    },
  • "maximumPayRate": {
    },
  • "billRatePeriod": "hourly",
  • "paymentBasis": "TIME",
  • "projectedCost": {
    },
  • "type": "JOB",
  • "jobProfile": {
    },
  • "classification": {
    },
  • "supervisoryOrganization": {
    },
  • "businessSite": {
    },
  • "costCenter": {
    },
  • "msp": {
    },
  • "startDate": "2026-01-01",
  • "endDate": "2026-06-30",
  • "expiryDate": "2025-12-01",
  • "externalTitle": "Data Analyst - Contract",
  • "externalDescription": "Initial posting for data analyst role",
  • "status": "DRAFT",
  • "created": "2026-01-15T10:15:30Z",
  • "modified": "2026-01-18T16:10:00Z",
  • "jobSummary": "6-month analytics assignment",
  • "customFields": [
    ],
  • "financialFields": [
    ]
}

Get job posting by uid

path Parameters
uid
required
string
Example: JR20f2de7d-da92-4a72-b69c-b8f4bcecb3ed

Unique ID of the job posting

Responses

Response samples

Content type
{
  • "uid": "JR20f2de7d-da92-4a72-b69c-b8f4bcecb3ed",
  • "referenceId": "1000123",
  • "requestedWorkerCount": 2,
  • "minimumBillRate": {
    },
  • "maximumBillRate": {
    },
  • "minimumPayRate": {
    },
  • "maximumPayRate": {
    },
  • "billRatePeriod": "hourly",
  • "paymentBasis": "TIME",
  • "projectedCost": {
    },
  • "type": "JOB",
  • "jobProfile": {
    },
  • "classification": {
    },
  • "supervisoryOrganization": {
    },
  • "businessSite": {
    },
  • "costCenter": {
    },
  • "msp": {
    },
  • "startDate": "2026-01-01",
  • "endDate": "2026-06-30",
  • "expiryDate": "2025-12-01",
  • "externalTitle": "Data Analyst - Contract",
  • "externalDescription": "Initial posting for data analyst role",
  • "status": "DRAFT",
  • "created": "2026-01-15T10:15:30Z",
  • "modified": "2026-01-18T16:10:00Z",
  • "jobSummary": "6-month analytics assignment",
  • "customFields": [
    ],
  • "financialFields": [
    ]
}

Update a job posting

path Parameters
uid
required
string
Example: JR20f2de7d-da92-4a72-b69c-b8f4bcecb3ed

job posting UID

Request Body schema:
required

Job posting properties to be updated

type
string
Enum: "JOB" "SOW"

Work posting type.

requestedWorkerCount
integer >= 1

Number of workers requested. Must be at least 1.

object (Amount)
object (Amount)
object (Amount)
object (Amount)
billRatePeriod
string (RatePeriod)
Enum: "hourly" "daily" "weekly" "bi_weekly" "monthly" "other" "on_invoice"
paymentBasis
string (JobPostingPaymentBasis)
Enum: "TIME" "TIME_AND_MATERIALS" "SOW"
object (Amount)
object

Job profile reference (provide uid or referenceId)

object

Classification reference (provide uid or referenceId)

object

Supervisory organization reference (provide uid or referenceId)

object

Business site reference (provide uid or referenceId)

object

Cost center reference (provide uid or referenceId)

object

MSP reference (provide uid or referenceId)

startDate
string <date>
endDate
string <date>
expiryDate
string <date>
externalTitle
string
externalDescription
string
status
string (JobPostingStatus)
Enum: "DRAFT" "PENDING" "IN_PROGRESS" "FILLED" "REJECTED" "CANCELLED" "DELETED"
jobSummary
string
Array of objects (CustomFieldPatchValue)
Array of objects (FinancialFieldPatchValue)

Responses

Request samples

Content type
{
  • "type": "JOB",
  • "requestedWorkerCount": 3,
  • "minimumBillRate": {
    },
  • "maximumBillRate": {
    },
  • "minimumPayRate": {
    },
  • "maximumPayRate": {
    },
  • "billRatePeriod": "hourly",
  • "paymentBasis": "TIME",
  • "projectedCost": {
    },
  • "jobProfile": {
    },
  • "classification": {
    },
  • "supervisoryOrganization": {
    },
  • "businessSite": {
    },
  • "costCenter": {
    },
  • "msp": {
    },
  • "startDate": "2026-02-01",
  • "endDate": "2026-07-31",
  • "expiryDate": "2026-01-20",
  • "externalTitle": "Senior Data Analyst - Contract",
  • "externalDescription": "Updated posting description",
  • "status": "DRAFT",
  • "jobSummary": "Updated assignment summary",
  • "customFields": [
    ],
  • "financialFields": [
    ]
}

Response samples

Content type
{
  • "uid": "JR20f2de7d-da92-4a72-b69c-b8f4bcecb3ed",
  • "referenceId": "1000123",
  • "requestedWorkerCount": 2,
  • "minimumBillRate": {
    },
  • "maximumBillRate": {
    },
  • "minimumPayRate": {
    },
  • "maximumPayRate": {
    },
  • "billRatePeriod": "hourly",
  • "paymentBasis": "TIME",
  • "projectedCost": {
    },
  • "type": "JOB",
  • "jobProfile": {
    },
  • "classification": {
    },
  • "supervisoryOrganization": {
    },
  • "businessSite": {
    },
  • "costCenter": {
    },
  • "msp": {
    },
  • "startDate": "2026-01-01",
  • "endDate": "2026-06-30",
  • "expiryDate": "2025-12-01",
  • "externalTitle": "Data Analyst - Contract",
  • "externalDescription": "Initial posting for data analyst role",
  • "status": "DRAFT",
  • "created": "2026-01-15T10:15:30Z",
  • "modified": "2026-01-18T16:10:00Z",
  • "jobSummary": "6-month analytics assignment",
  • "customFields": [
    ],
  • "financialFields": [
    ]
}

Delete job posting by uid

path Parameters
uid
required
string
Example: JR20f2de7d-da92-4a72-b69c-b8f4bcecb3ed

job posting UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

users

List users by criteria

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: page number, starting from 1

search
string

Search users by UID, display name, reference id, or email

referenceIds
Array of strings

Return only users with matching reference ids

userEmails
Array of strings

Return only users with matching email addresses

Responses

Response samples

Content type
{
  • "totalCount": 1,
  • "totalPages": 1,
  • "users": [
    ]
}

Create a user

Creates a user and links it to a worker/person by email. If a worker/person with the same primary email already exists, the user is linked to that existing worker/person record. If no worker/person is found, a new minimal worker/person record is created. Use personUid from the response as the worker uid in Workers v2 endpoints.

Request Body schema:
required

New user to be created

firstName
required
string non-empty

First name

lastName
required
string non-empty

Last name

email
required
string <email>

Unique user email

type
required
string (UserType)
Enum: "EXTERNAL_APPROVER" "MSP_ADMIN" "MSP_USER" "SUPPORT_USER" "TENANT_USER" "UNKNOWN"

User role/type

status
required
string (UserStatus)
Enum: "ENABLED" "DISABLED"

User status

referenceId
string

Reference id

object

MSP reference. Provide either uid or referenceId.

sendEmail
boolean
Default: false

Controls invitation email sending during user creation.

Responses

Request samples

Content type
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "user@example.com",
  • "type": "EXTERNAL_APPROVER",
  • "status": "ENABLED",
  • "referenceId": "string",
  • "msp": {
    },
  • "sendEmail": false
}

Response samples

Content type
{
  • "uid": "U421e4abe-12c4-4699-871a-a8aa43e5e772",
  • "referenceId": "string",
  • "displayName": "string",
  • "personUid": "Pb83c8c1b-d05d-4859-94a6-90abee06f5c7",
  • "name": {
    },
  • "email": "user@example.com",
  • "type": "EXTERNAL_APPROVER",
  • "status": "ENABLED",
  • "msp": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "lastLogin": "2019-08-24T14:15:22Z"
}

Get user by uid

path Parameters
uid
required
string
Example: U421e4abe-12c4-4699-871a-a8aa43e5e772

User UID

Responses

Response samples

Content type
{
  • "uid": "U421e4abe-12c4-4699-871a-a8aa43e5e772",
  • "referenceId": "string",
  • "displayName": "string",
  • "personUid": "Pb83c8c1b-d05d-4859-94a6-90abee06f5c7",
  • "name": {
    },
  • "email": "user@example.com",
  • "type": "EXTERNAL_APPROVER",
  • "status": "ENABLED",
  • "msp": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "lastLogin": "2019-08-24T14:15:22Z"
}

Patch a user

path Parameters
uid
required
string
Example: U421e4abe-12c4-4699-871a-a8aa43e5e772

User UID

Request Body schema:
required

User properties to be updated

type
string (UserType)
Enum: "EXTERNAL_APPROVER" "MSP_ADMIN" "MSP_USER" "SUPPORT_USER" "TENANT_USER" "UNKNOWN"

User role/type

status
string (UserStatus)
Enum: "ENABLED" "DISABLED"

User status

object

MSP reference to set/replace. Must include at least one of uid or referenceId when present.

Responses

Request samples

Content type
{
  • "type": "EXTERNAL_APPROVER",
  • "status": "ENABLED",
  • "msp": {
    }
}

Response samples

Content type
{
  • "uid": "U421e4abe-12c4-4699-871a-a8aa43e5e772",
  • "referenceId": "string",
  • "displayName": "string",
  • "personUid": "Pb83c8c1b-d05d-4859-94a6-90abee06f5c7",
  • "name": {
    },
  • "email": "user@example.com",
  • "type": "EXTERNAL_APPROVER",
  • "status": "ENABLED",
  • "msp": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "lastLogin": "2019-08-24T14:15:22Z"
}

Delete user by uid

path Parameters
uid
required
string
Example: U421e4abe-12c4-4699-871a-a8aa43e5e772

User UID

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

timesheets

Get Timesheet details by UID

path Parameters
uid
required
string
Example: T9er43993-d212-5c11-10j3-npp3b226h3a3

timesheet UID

Responses

Response samples

Content type
{
  • "uid": "TS9er43993-d212-5c11-10j3-npp3b226h3a3",
  • "referenceId": "string",
  • "status": "WAITING_FOR_SUBMISSION",
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "approvalDate": "2019-08-24T14:15:22Z",
  • "engagement": {
    },
  • "person": {
    },
  • "lineItems": [
    ],
  • "approvals": [
    ],
  • "desiredStatus": "WAITING_FOR_SUBMISSION"
}

Approve timesheet

path Parameters
uid
required
string
Example: T9er43993-d212-5c11-10j3-npp3b226h3a3

timesheet UID

Request Body schema:
required

Approve timesheet

approverPersonUid
string
decision
string (TimesheetApprovalStatus)
Enum: "APPROVED" "REJECTED"
reason
string

Responses

Request samples

Content type
{
  • "approverPersonUid": "P0df55682-e400-4b66-87a7-bea6a183a4c8",
  • "decision": "APPROVED",
  • "reason": "string"
}

Response samples

Content type
{
  • "uid": "TS9er43993-d212-5c11-10j3-npp3b226h3a3",
  • "referenceId": "string",
  • "status": "WAITING_FOR_SUBMISSION",
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "approvalDate": "2019-08-24T14:15:22Z",
  • "engagement": {
    },
  • "person": {
    },
  • "lineItems": [
    ],
  • "approvals": [
    ],
  • "desiredStatus": "WAITING_FOR_SUBMISSION"
}

expenses

Get Expense details by UID

path Parameters
uid
required
string
Example: E14bd4098-b7d9-492a-9a6f-b52ba63df730

expense UID

Responses

Response samples

Content type
{
  • "uid": "E14bd4098-b7d9-492a-9a6f-b52ba63df730",
  • "referenceId": "string",
  • "status": "PENDING",
  • "description": "string",
  • "notes": "string",
  • "vendor": "string",
  • "spentDate": "2019-08-24",
  • "approvalDate": "2019-08-24T14:15:22Z",
  • "engagement": {
    },
  • "person": {
    },
  • "costCenter": {
    },
  • "supplier": {
    },
  • "expenseCategory": {
    },
  • "amount": {
    },
  • "fee": {
    },
  • "tax": {
    },
  • "approvals": [
    ]
}

Approve expense

path Parameters
uid
required
string
Example: E14bd4098-b7d9-492a-9a6f-b52ba63df730

expense UID

Request Body schema:
required

Approve expense

approverPersonUid
string
decision
string (ExpenseApprovalStatus)
Enum: "APPROVED" "REJECTED"
reason
string

Responses

Request samples

Content type
{
  • "approverPersonUid": "P0df55682-e400-4b66-87a7-bea6a183a4c8",
  • "decision": "APPROVED",
  • "reason": "string"
}

Response samples

Content type
{
  • "uid": "E14bd4098-b7d9-492a-9a6f-b52ba63df730",
  • "referenceId": "string",
  • "status": "PENDING",
  • "description": "string",
  • "notes": "string",
  • "vendor": "string",
  • "spentDate": "2019-08-24",
  • "approvalDate": "2019-08-24T14:15:22Z",
  • "engagement": {
    },
  • "person": {
    },
  • "costCenter": {
    },
  • "supplier": {
    },
  • "expenseCategory": {
    },
  • "amount": {
    },
  • "fee": {
    },
  • "tax": {
    },
  • "approvals": [
    ]
}

processes

List all processes

query Parameters
limit
integer
Default: 20

Pagination parameter: single page size

page
integer
Default: 1

Pagination parameter: which page of results to return (page numbers start from 1)

processDefinitionUids
Array of strings

List of process definition uids that the returned processes are instanced from

processStatuses
Array of strings (ProcessStatus)
Items Enum: "ACTIVE" "COMPLETED" "COMPLETED_WITH_ERRORS" "DELETED"

List of statuses that return corresponding processes

Responses

Response samples

Content type
{
  • "totalCount": 9876,
  • "totalPages": 10,
  • "processes": [
    ]
}

processDefinitions

List all processDefinitions

query Parameters
processDefinitionStatus
string (ProcessDefinitionStatus)
Enum: "ACTIVE" "INACTIVE"

Exclude process definitions without the provided status

processDefinitionResourceType
Array of strings (OptionalEngagementReferenceType)
Items Enum: "accountablePerson" "businessSite" "classification" "company" "costCenter" "financialDetails" "holidaySchedule" "jobApplication" "jobProfile" "jobFamily" "managerDetails" "msp" "remoteWorkAddress" "supervisoryOrganization" "supplier" "terminationReason" "workSchedule" "jobClassifications" "jobFamilyGroup"

List of resource types the returned process definitions target.

Responses

Response samples

Content type
{
  • "processDefinitions": [
    ]
}

roleAssignments

This API supports the management of roleAssignments i.e. the relationship between

  • a role as identified by a roleReferenceId
  • a condition - one of businessSite, org or costCenter
  • one of more assignees identified via workerId

List all role assignments

query Parameters
roleReferenceIds
Array of strings

List of reference Ids of roles to be included in the response

Responses

Response samples

Content type
{
  • "roleAssignments": [
    ]
}

Update role assignments

The API operates incrementally i.e. new role assignments can be added or existing ones modified via PATCH - it is not necessary to load the entire roleAssignment set in one request. The request may be partially accepted even if it contains invalid assignments and is marked with Bad Request status. All incorrect assignments will be skipped.

Request Body schema:
required

Role Assignments to be updated

Array of objects (RoleAssignmentUpdate)

Responses

Request samples

Content type
{
  • "roleAssignments": [
    ]
}

Response samples

Content type
{
  • "roleAssignments": [
    ]
}

financialFieldsValues

This API allows the set of drop-down values for a financial field, referenced via financialFieldReferenceId, to be updated. The API operates incrementally i.e. new field values can be added via PATCH. Likewise the display name of a value can be updated by specifying the referenceId of the individual value object. In order to remove a value from the available value set, and therefore prevent it appearing in drop-downs, its status should be set to INACTIVE.

List all financial fields values

query Parameters
financialFieldReferenceIds
Array of strings

List of reference Ids of financial fields to be included in the response

Responses

Response samples

Content type
{
  • "financialFieldsValues": [
    ]
}

Update financial fields values

Request Body schema:
required

Financial Fields values to be updated

Array of objects (FinancialFieldValuesUpdate)

Responses

Request samples

Content type
{
  • "financialFieldsValues": [
    ]
}

Response samples

Content type
{
  • "financialFieldsValues": [
    ]
}

pendingChanges

Discard engagement pending changes

Discards any pending changes for an engagement and terminates the relevant processes

path Parameters
workerUid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

worker UID

engagementUid
required
string
Example: E0df55682-e400-4b66-87a7-bea6a183a4c8

engagement UID

query Parameters
reason
required
string

termination reason for the relevant processes

Responses

Response samples

Content type
{
  • "numberOfPendingChangesDiscarded": 5
}

spendApprovalLimits

Get Worker spend approval limits

Get worker's spend approval limits

path Parameters
workerUid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

person UID

Responses

Response samples

Content type
{
  • "spendApprovalLimits": [
    ]
}

Update Worker spend approval limits

Replace all worker's spend approval limits with the set of limits provided in the request body.

Existing limits not included in the request will be removed.

Limits with amount set to 0 will be removed.

path Parameters
workerUid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

person UID

Request Body schema:
required
Array of objects (SpendApprovalLimit)

Responses

Request samples

Content type
{
  • "spendApprovalLimits": [
    ]
}

Response samples

Content type
{
  • "spendApprovalLimits": [
    ]
}

Patch Worker spend approval limits

Selectively update worker's spend approval limits.

Only limit(s) specified in the request body will be modified.

Limits with amount set to 0 will be removed.

path Parameters
workerUid
required
string
Example: P0df55682-e400-4b66-87a7-bea6a183a4c8

person UID

Request Body schema:
required
Array of objects (SpendApprovalLimit)

Responses

Request samples

Content type
{
  • "spendApprovalLimits": [
    ]
}

Response samples

Content type
{
  • "spendApprovalLimits": [
    ]
}