API docs by Redocly

Beeline Supplier and Talent API (0.1)

Download OpenAPI specification:Download

JSON REST API used for interacting with Beeline Supplier and Talent Applications

The resources to be accessed are business objects within Beeline representing either transactional (e.g. worker, job posting, candidate) or reference (e.g. cost center, job profile) data. Separate endpoints are provided for each of the resource types. RESTful conventions mean that the API will typically support the following verbs for each of the resource endpoints:

  • GET which can be used to obtain a collection of resources or a specific resource by reference
  • POST to create a new resource
  • PATCH to update an existing resource

Resource Types

The following resources are currently supported

  • Worker - A representation of an individual worker in the Beeline system
  • Job Posting - A job request originating from a Beeline VMS tenant
  • Candidate - A supplier's submission of a particular worker against a particular job posting

Authentication

An OAuth2 Client Credentials flow should first be used to obtain a bearer token which must be included in all API calls in order to authenticate the request. To request a token, the client must POST to the /api/gwg/supplier/oauth/token endpoint on their Beeline environment specifying a client_id and client_secret. The client_id is configured per integration via the Beeline Supplier Application by the supplier administrator.

Authentication

Obtain an access token via an OAuth2 client credentials grant

To use the Beeline API, the supplier must create an integration client in their Beeline Supplier application. They will receive a client ID and client secret, which they can exchange for an access token via this API using a client credentials grant.

Pass the client_id and client_secret in the Authorization header using Basic Authentication. Alternatively, You may pass client_id and client_secret in the request body.

Authorizations:
BasicAuth
Request Body schema: application/x-www-form-urlencoded
grant_type
required
string

Grant Type

client_id
string

Client ID

client_secret
string

Client Secret

scope
string

Scope

audience
string

Audience

Responses

Response samples

Content type
application/json
{
  • "token_type": "string",
  • "access_token": "string",
  • "expires_in": 0
}

Candidates

List all candidates

List all candidates that a supplier has created. Can be filtered per job posting.

Authorizations:
OAuth2ClientCredentials
query Parameters
limit
integer

Limit

offset
integer

Offset

jobPostingUid
string

Job Posting Uid

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "totalCount": 0
}

Create candidate

Create a candidate for a certain worker against a certain job posting.

Authorizations:
OAuth2ClientCredentials
Request Body schema: application/json
uid
string
status
string
Enum: "CREATED" "SUBMITTING" "SUBMITTED" "RESCINDED" "SUBMISSION_FAILED" "ACCEPTED" "REJECTED"
jobPostingUid
required
string
enterpriseJobPostingNumber
string
rateCurrency
string

ISO 4217 currency code (e.g., USD, EUR)

ratePeriod
string (RatePeriod)
Enum: "HOURLY" "DAILY" "WEEKLY" "BI_WEEKLY" "MONTHLY" "ON_INVOICE"
workerUid
required
string
email
required
string <email>
created
string <date-time>
modified
string <date-time>
Array of objects (CustomField)
object (Name)
Array of objects (Phone)
dateOfBirth
string <date>
partialNationalId
string
fullNationalId
string
Array of objects (AddressField)
resourceType
string
dateAvailable
string <date>
formerConsultant
boolean
formerEmployee
boolean
Array of objects (RateAmount)
Array of objects (RateAmount)
supplierSubmittalComments
string
submissionErrorMessage
string

A detailed error message in case the candidate submission has failed.

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "status": "CREATED",
  • "jobPostingUid": "string",
  • "enterpriseJobPostingNumber": "string",
  • "rateCurrency": "string",
  • "ratePeriod": "HOURLY",
  • "workerUid": "string",
  • "email": "user@example.com",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "customFields": [
    ],
  • "name": {
    },
  • "phones": [
    ],
  • "dateOfBirth": "2019-08-24",
  • "partialNationalId": "string",
  • "fullNationalId": "string",
  • "addresses": [
    ],
  • "resourceType": "string",
  • "dateAvailable": "2019-08-24",
  • "formerConsultant": true,
  • "formerEmployee": true,
  • "billRates": [
    ],
  • "payRates": [
    ],
  • "supplierSubmittalComments": "string",
  • "submissionErrorMessage": "string"
}

Response samples

Content type
application/json
{
  • "uid": "string",
  • "status": "CREATED",
  • "jobPostingUid": "string",
  • "enterpriseJobPostingNumber": "string",
  • "rateCurrency": "string",
  • "ratePeriod": "HOURLY",
  • "workerUid": "string",
  • "email": "user@example.com",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "customFields": [
    ],
  • "name": {
    },
  • "phones": [
    ],
  • "dateOfBirth": "2019-08-24",
  • "partialNationalId": "string",
  • "fullNationalId": "string",
  • "addresses": [
    ],
  • "resourceType": "string",
  • "dateAvailable": "2019-08-24",
  • "formerConsultant": true,
  • "formerEmployee": true,
  • "billRates": [
    ],
  • "payRates": [
    ],
  • "supplierSubmittalComments": "string",
  • "submissionErrorMessage": "string"
}

Rescind candidate

Revoke a candidate that has already been submitted to the VMS. This candidate can be edited and re-submitted, if that is desirable. Operation only supported for Beeline Professional job postings.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the candidate to rescind

Responses

Response samples

Content type
application/json
{
  • "uid": "string",
  • "status": "CREATED",
  • "jobPostingUid": "string",
  • "enterpriseJobPostingNumber": "string",
  • "rateCurrency": "string",
  • "ratePeriod": "HOURLY",
  • "workerUid": "string",
  • "email": "user@example.com",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "customFields": [
    ],
  • "name": {
    },
  • "phones": [
    ],
  • "dateOfBirth": "2019-08-24",
  • "partialNationalId": "string",
  • "fullNationalId": "string",
  • "addresses": [
    ],
  • "resourceType": "string",
  • "dateAvailable": "2019-08-24",
  • "formerConsultant": true,
  • "formerEmployee": true,
  • "billRates": [
    ],
  • "payRates": [
    ],
  • "supplierSubmittalComments": "string",
  • "submissionErrorMessage": "string"
}

Submit candidate

Submit a candidate to the VMS. At this point the candidate will be visible in the VMS, and selection and approval processes can begin.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the candidate to submit

query Parameters
supplierUserId
string

SupplierUserId is a userId starting with the SUR prefix that is received from the /getBeelineUsers endpoint (required for Beeline Enterprise candidates only)

Responses

Response samples

Content type
application/json
{
  • "uid": "string",
  • "status": "CREATED",
  • "jobPostingUid": "string",
  • "enterpriseJobPostingNumber": "string",
  • "rateCurrency": "string",
  • "ratePeriod": "HOURLY",
  • "workerUid": "string",
  • "email": "user@example.com",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "customFields": [
    ],
  • "name": {
    },
  • "phones": [
    ],
  • "dateOfBirth": "2019-08-24",
  • "partialNationalId": "string",
  • "fullNationalId": "string",
  • "addresses": [
    ],
  • "resourceType": "string",
  • "dateAvailable": "2019-08-24",
  • "formerConsultant": true,
  • "formerEmployee": true,
  • "billRates": [
    ],
  • "payRates": [
    ],
  • "supplierSubmittalComments": "string",
  • "submissionErrorMessage": "string"
}

Get candidate

Fetch candidate details for a specific candidate.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the candidate to get

Responses

Response samples

Content type
application/json
{
  • "uid": "string",
  • "status": "CREATED",
  • "jobPostingUid": "string",
  • "enterpriseJobPostingNumber": "string",
  • "rateCurrency": "string",
  • "ratePeriod": "HOURLY",
  • "workerUid": "string",
  • "email": "user@example.com",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "customFields": [
    ],
  • "name": {
    },
  • "phones": [
    ],
  • "dateOfBirth": "2019-08-24",
  • "partialNationalId": "string",
  • "fullNationalId": "string",
  • "addresses": [
    ],
  • "resourceType": "string",
  • "dateAvailable": "2019-08-24",
  • "formerConsultant": true,
  • "formerEmployee": true,
  • "billRates": [
    ],
  • "payRates": [
    ],
  • "supplierSubmittalComments": "string",
  • "submissionErrorMessage": "string"
}

Update candidate

Update candidate details for a specific candidate. Candidate details cannot be updated once the candidate has been submitted - in that scenario, the candidate must be rescinded, edited and then resubmitted.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the candidate to update

Request Body schema: application/json
uid
string
status
string
Enum: "CREATED" "SUBMITTING" "SUBMITTED" "RESCINDED" "SUBMISSION_FAILED" "ACCEPTED" "REJECTED"
jobPostingUid
required
string
enterpriseJobPostingNumber
string
rateCurrency
string

ISO 4217 currency code (e.g., USD, EUR)

ratePeriod
string (RatePeriod)
Enum: "HOURLY" "DAILY" "WEEKLY" "BI_WEEKLY" "MONTHLY" "ON_INVOICE"
workerUid
required
string
email
required
string <email>
created
string <date-time>
modified
string <date-time>
Array of objects (CustomField)
object (Name)
Array of objects (Phone)
dateOfBirth
string <date>
partialNationalId
string
fullNationalId
string
Array of objects (AddressField)
resourceType
string
dateAvailable
string <date>
formerConsultant
boolean
formerEmployee
boolean
Array of objects (RateAmount)
Array of objects (RateAmount)
supplierSubmittalComments
string
submissionErrorMessage
string

A detailed error message in case the candidate submission has failed.

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "status": "CREATED",
  • "jobPostingUid": "string",
  • "enterpriseJobPostingNumber": "string",
  • "rateCurrency": "string",
  • "ratePeriod": "HOURLY",
  • "workerUid": "string",
  • "email": "user@example.com",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "customFields": [
    ],
  • "name": {
    },
  • "phones": [
    ],
  • "dateOfBirth": "2019-08-24",
  • "partialNationalId": "string",
  • "fullNationalId": "string",
  • "addresses": [
    ],
  • "resourceType": "string",
  • "dateAvailable": "2019-08-24",
  • "formerConsultant": true,
  • "formerEmployee": true,
  • "billRates": [
    ],
  • "payRates": [
    ],
  • "supplierSubmittalComments": "string",
  • "submissionErrorMessage": "string"
}

Response samples

Content type
application/json
{
  • "uid": "string",
  • "status": "CREATED",
  • "jobPostingUid": "string",
  • "enterpriseJobPostingNumber": "string",
  • "rateCurrency": "string",
  • "ratePeriod": "HOURLY",
  • "workerUid": "string",
  • "email": "user@example.com",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "customFields": [
    ],
  • "name": {
    },
  • "phones": [
    ],
  • "dateOfBirth": "2019-08-24",
  • "partialNationalId": "string",
  • "fullNationalId": "string",
  • "addresses": [
    ],
  • "resourceType": "string",
  • "dateAvailable": "2019-08-24",
  • "formerConsultant": true,
  • "formerEmployee": true,
  • "billRates": [
    ],
  • "payRates": [
    ],
  • "supplierSubmittalComments": "string",
  • "submissionErrorMessage": "string"
}

Remove candidate media

Remove candidate media for a specific candidate.

Authorizations:
OAuth2ClientCredentials
path Parameters
candidateUid
required
string

Uid of the candidate for which to remove media

mediaUid
required
string

Uid of the media to remove

Responses

Response samples

Content type
application/json
true

Add candidate media (multipart)

Add candidate media for a specific candidate via form data.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the candidate for which to add media

Request Body schema: multipart/form-data
file
string <binary>

The media file to be uploaded.

filename
string

The name of the file being uploaded.

mediaType
string (MediaType)
Enum: "RESUME" "OTHER_WORKER_DOCUMENT"

Responses

Response samples

Content type
application/json
{
  • "uid": "string",
  • "filename": "string",
  • "contentType": "string",
  • "mediaType": "RESUME",
  • "sizeInBytes": 0
}

Add candidate media

Add candidate media for a specific candidate.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the candidate for which to add media

Request Body schema: application/json
file
required
string

Base64 encoded string representation of the file to add.

filename
required
string
mediaType
required
string (MediaType)
Enum: "RESUME" "OTHER_WORKER_DOCUMENT"

Responses

Request samples

Content type
application/json
{
  • "file": "string",
  • "filename": "string",
  • "mediaType": "RESUME"
}

Response samples

Content type
application/json
{
  • "uid": "string",
  • "filename": "string",
  • "contentType": "string",
  • "mediaType": "RESUME",
  • "sizeInBytes": 0
}

Get candidate media

Get candidate media for a specific candidate.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the candidate from which to get media

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get candidate custom field metadata

Different enterprise VMSs will have different configurations of required fields for candidate submission. This endpoint describes the custom fields that are available for a given posting.

Authorizations:
OAuth2ClientCredentials
query Parameters
jobPostingUid
required
string

Job Posting Uid

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Job Postings

Get job posting details

Fetch job posting details for a specific job posting.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the job posting to get

Responses

Response samples

Content type
application/json
{
  • "uid": "string",
  • "status": "IN_PROGRESS",
  • "sourceVMS": "string",
  • "requestedWorkers": 0,
  • "title": "string",
  • "description": "string",
  • "expiryDate": "2019-08-24",
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "location": "string",
  • "enterpriseJobPostingNumber": "string",
  • "classificationName": "string",
  • "managerName": "string",
  • "enterpriseName": "string",
  • "clientName": "string",
  • "clientUid": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "beelineProfessionalRates": {
    },
  • "beelineEnterpriseRates": {
    },
  • "notes": {
    },
  • "customFields": [
    ]
}

List all job postings

List all job postings that have been made available to the supplier by enterprise VMSs.

Authorizations:
OAuth2ClientCredentials
query Parameters
limit
integer

Limit

offset
integer

Offset

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "totalCount": 0
}

Beeline Users

Get a list of verified Supplier Experience users

Fetch a list of Supplier Experience users that have verified their accounts with the Beeline Enterprise client that issued the specified job posting.

Authorizations:
OAuth2ClientCredentials
path Parameters
jobPostingUid
required
string

The job posting UID is used to fetch all Supplier users eligible to submit candidates to that job posting.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Workers

List all workers

List all of the workers that have been previously added by the supplier.

Authorizations:
OAuth2ClientCredentials
query Parameters
limit
integer

Limit

offset
integer

Offset

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "totalCount": 0
}

Create worker

Authorizations:
OAuth2ClientCredentials
Request Body schema: application/json
uid
string
required
object (NameInfo)
email
string <email>
phone
string

Phone number in e164 format.

object (Address)
dateOfBirth
string <date>
created
string <date-time>
modified
string <date-time>
gender
string
Enum: "MALE" "FEMALE" "PREFER_NOT_TO_ANSWER" "OTHER"
partialNationalId
string
fullNationalId
string

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "name": {
    },
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "dateOfBirth": "2019-08-24",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "gender": "MALE",
  • "partialNationalId": "string",
  • "fullNationalId": "string"
}

Response samples

Content type
application/json
{
  • "uid": "string",
  • "name": {
    },
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "dateOfBirth": "2019-08-24",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "gender": "MALE",
  • "partialNationalId": "string",
  • "fullNationalId": "string"
}

Get worker by uid

Get worker details for a specific worker.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the worker to get

Responses

Response samples

Content type
application/json
{
  • "uid": "string",
  • "name": {
    },
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "dateOfBirth": "2019-08-24",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "gender": "MALE",
  • "partialNationalId": "string",
  • "fullNationalId": "string"
}

Update worker by uid

Update worker details for a specific worker.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the worker to update

Request Body schema: application/json
uid
string
required
object (NameInfo)
email
string <email>
phone
string

Phone number in e164 format.

object (Address)
dateOfBirth
string <date>
created
string <date-time>
modified
string <date-time>
gender
string
Enum: "MALE" "FEMALE" "PREFER_NOT_TO_ANSWER" "OTHER"
partialNationalId
string
fullNationalId
string

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "name": {
    },
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "dateOfBirth": "2019-08-24",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "gender": "MALE",
  • "partialNationalId": "string",
  • "fullNationalId": "string"
}

Response samples

Content type
application/json
{
  • "uid": "string",
  • "name": {
    },
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "dateOfBirth": "2019-08-24",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "gender": "MALE",
  • "partialNationalId": "string",
  • "fullNationalId": "string"
}

Webhook Subscriptions

Create Webhook Subscription

Register a new webhook URL for receiving event notifications.

Authorizations:
OAuth2ClientCredentials
Request Body schema: application/json
callbackUrl
required
string <uri>

The URL to which notifications will be sent.

secretKey
required
string

A secret key used for HMAC signature validation.

eventType
required
string (WebhookEventType)
Value: "JOB_POSTING_RELEASED"

The event type the supplier wants to subscribe to.

Responses

Request samples

Content type
application/json
{
  • "callbackUrl": "http://example.com",
  • "secretKey": "string",
  • "eventType": "JOB_POSTING_RELEASED"
}

Response samples

Content type
application/json
{
  • "uid": "string",
  • "callbackUrl": "http://example.com",
  • "secretKey": "string",
  • "eventType": "JOB_POSTING_RELEASED"
}

List Webhook Subscriptions

Fetch all webhook subscriptions.

Authorizations:
OAuth2ClientCredentials
query Parameters
limit
integer

Limit

offset
integer

Offset

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "totalCount": 0
}

Get Webhook Subscription by uid

Get subscription details for a particular subscription.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the subscription to get.

Responses

Response samples

Content type
application/json
{
  • "uid": "string",
  • "callbackUrl": "http://example.com",
  • "secretKey": "string",
  • "eventType": "JOB_POSTING_RELEASED"
}

Update Webhook Subscription

Update one or more fields of an existing subscription. Only the provided fields will be updated.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the subscription to update.

Request Body schema: application/json
callbackUrl
string <uri>

The URL to which notifications will be sent.

secretKey
string

A secret key used for HMAC signature validation.

eventType
string (WebhookEventType)
Value: "JOB_POSTING_RELEASED"

The event type the supplier wants to subscribe to.

Responses

Request samples

Content type
application/json
{
  • "callbackUrl": "http://example.com",
  • "secretKey": "string",
  • "eventType": "JOB_POSTING_RELEASED"
}

Response samples

Content type
application/json
{
  • "uid": "string",
  • "callbackUrl": "http://example.com",
  • "secretKey": "string",
  • "eventType": "JOB_POSTING_RELEASED"
}

Delete Webhook Subscription

Delete an existing webhook subscription.

Authorizations:
OAuth2ClientCredentials
path Parameters
uid
required
string

Uid of the subscription to delete.

Responses

Webhook Examples

Consume Job Posting Released event

Example of the API implementation to receive a JOB_POSTING_RELEASED event.

Authorizations:
OAuth2ClientCredentials
header Parameters
X-Signature
required
string

The Base64 encoded HMAC-SHA256 signature of the request body using the secret key.

X-Signature-Algorithm
required
string

Specifies the algorithm used for HMAC signature. Value is always "HMAC-SHA256".

Request Body schema: application/json
eventType
required
string (WebhookEventType)
Value: "JOB_POSTING_RELEASED"

The event type the supplier wants to subscribe to.

required
object

Responses

Request samples

Content type
application/json
{
  • "eventType": "JOB_POSTING_RELEASED",
  • "data": {
    }
}