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
}

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": [
    ]
}