Workstream Public API (1.0.0)

Download OpenAPI specification:Download

API Reference

The Workstream API is a modern, RESTful API. Our API has predictable resource-oriented URLs, supports HTTPS authentication, verbs and response codes, and returns JSON-encoded responses.

Note: Old APIs will be deprecated, please refer to this API documentation for new API usages.

Authorization

The Workstream API uses OAuth 2.0 Bearer access tokens to authenticate requests. You can view and manage your access tokens in the Workstream Dashboard.

To generate an access token, simply click on Generate token, give it a name, and select the permissions(i.e. Applicants, Employees, Positions) to attach to it. The token expires in 7 days.

You can also manage your tokens through API, as shown in the next section.

Create a new access token

Creates a new access token.

Request
query Parameters
grant_type
required
string

Grant type of access token, please use client_credentials.

Example: grant_type=client_credentials
client_id
required
string

Client credentials provided as part of your application. This can be retrieved from the Dashboard under Company->Integrations->Access Tokens.

client_secret
required
string

The password used to authenticate your application. This can be retrieved from the Dashboard under Company->Integrations->Access Tokens.

name
required
string

Name of the access token displayed in the Dashboard.

scopes
required
Array of strings

Permission scopes of access token.

Items Enum: "positions" "position_applications" "employees" "team_members" "locations" "departments"
Responses
200

OK

401

Unauthorized

post/tokens
Request samples
Response samples
application/json
{
  • "name": "token1",
  • "token": "OtrQV4Gz7nwLouCm-ZLqiSxdwJEMEAFGx___GcNxES8",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_in": 604800,
  • "scopes": [
    ]
}

Refresh the access token

Refresh the access token.

Request
query Parameters
grant_type
required
string

Grant type of access token, please use client_credentials.

Example: grant_type=client_credentials
client_id
required
string

Client credentials provided as part of your application. This can be retrieved from the Dashboard under Company->Integrations->Access Tokens.

client_secret
required
string

The password used to authenticate your application. This can be retrieved from the Dashboard under Company->Integrations->Access Tokens.

token
required
string

The access token needs to be refreshed

Responses
200

OK

401

Unauthorized

post/tokens/refresh_token
Request samples
Response samples
application/json
{
  • "name": "token1",
  • "token": "OtrQV4Gz7nwLouCm-ZLqiSxdwJEMEAFGx___GcNxES8",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_in": 604800,
  • "scopes": [
    ]
}

Revoke an existing access token

Revokes an existing access token.

Request
query Parameters
token
required
string

The access token to revoke.

Example: token=AqrqBVwadstAdr_Ens0j5iHLug3gVKkOnTnDXvSDhmo
client_id
required
string

Client credentials provided as part of your application. This can be retrieved from the Dashboard under Company->Integrations->Access Tokens.

client_secret
required
string

The password used to authenticate your application. This can be retrieved from the Dashboard under Company->Integrations->Access Tokens.

Responses
200

OK

403

Unauthorized Client

post/revoke
Request samples
Response samples
application/json
{ }

Positions

Positions represent open job requisitions within your company that are looking to be filled.

Retrieve an existing Position

Retrieves an existing Position.

SecuritybearerAuth
Request
path Parameters
uuid
required
string <uuid>
query Parameters
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(location, custom_fields)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/positions/{uuid}
Request samples
Response samples
application/json
{
  • "uuid": "c59c9852-2584-11ee-be56-0242ac120002",
  • "digest_key": "40ad0bd6836b9e5cfedbf28e7c907fe229a99a2a",
  • "title": "Customer Success Associate",
  • "overview": "We are looking for a full-time, dedicated, and passionate individual to join our growing team.",
  • "status": "published",
  • "number": "1845",
  • "access": "public",
  • "pay_amount": "15$",
  • "pay_frequency": "hourly",
  • "job_type": "full_time",
  • "normalized_titles": "string",
  • "remote_type": "on_site",
  • "location": {
    },
  • "custom_fields": [
    ]
}

List existing Positions

Lists existing Positions with the input parameters.

SecuritybearerAuth
Request
query Parameters
title
string

Returns positions with the input title.

Example: title=Cook
status
string

Returns positions with the input status.

Enum: "pending" "published" "closed" "deleted"
Example: status=published
access
string

Returns positions with input access.

Enum: "link_only" "public"
Example: access=link_only
location[name]
string

Returns positions with the input location's name.

Example: location[name]=SF%20Store
created_at.gte
string <timestamp>

Returns positions created after or equals to the input date.

Example: created_at.gte=2022-09-30 00:00:00.000Z
created_at.lte
string

Returns positions created before or equals to the input date.

Example: created_at.lte=2022-09-30 00:00:00.000Z
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(location, custom_fields)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/positions
Request samples
Response samples
application/json
{
  • "data": [
    ]
}

Applicants

Applicants represent people who have applied for positions within your company.

Retrieve an existing Applicant

Retrieves an existing Applicant.

SecuritybearerAuth
Request
path Parameters
uuid
required
string <uuid>
query Parameters
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated

Example: embed=(position, location, department, notes, tags, candidate_info)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/position_applications/{uuid}
Request samples
Response samples
application/json
{
  • "uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
  • "digest_key": "108eeee1",
  • "referer_source": "Others",
  • "email": "joblexxx@gmail.com",
  • "phone": "4321012345",
  • "first_name": "Joey",
  • "last_name": "White",
  • "name": "Joey White",
  • "status": "in_progress",
  • "sms_phone_number": "+14155693009",
  • "global_phone_number": "+15151515151",
  • "sms_notification": true,
  • "current_stage": "Application",
  • "hired_at": "2022-12-01 08:00:00",
  • "application_date": "2019-08-24",
  • "latest_interview_date": "2022-12-01",
  • "position": {
    },
  • "location": {
    },
  • "department": {
    },
  • "notes": [
    ],
  • "tags": [
    ],
  • "candidate_info": [
    ]
}

List Applicant's custom forms

Returns the questions and answers of forms filled in by an existing Applicant.

SecuritybearerAuth
Request
path Parameters
uuid
required
string <uuid>
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/position_applications/{uuid}/forms
Request samples
Response samples
application/json
{
  • "data": [
    ]
}

List existing Applicants

Lists existing Applicants with the input parameters.

SecuritybearerAuth
Request
query Parameters
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated

Example: embed=(position, location, department, notes, tags, candidate_info)
status
string

Returns applicants with the input status.

Enum: "in_progress" "hired" "rejected"
Example: status=in_progress
first_name
string

Returns applicants with the input first_name.

Example: first_name=Andy
last_name
string

Returns applicants with the input last_name.

Example: last_name=Lee
name
string

Returns applicants with the input name.

Example: name=Andy%20Lee
current_stage
string

Returns applicants with the input position stage.

Example: current_stage=Onsite%20Interview
position[uuid]
string <uuid>

Returns applicants with the input position's UUID.

Example: position[uuid]=67161b3c-2584-11ee-be56-0242ac120002
location[name]
string

Returns applicants with the input location's name.

Example: location[name]=SF%20store
tag[name]
string

Returns applicants with the input applicant tag's name.

Example: tag[name]=cook
note[content]
string

Returns applicants with the input applicant note's content.

Example: note[content]=He is a good applicant
created_at.gte
string <timestamp>

Returns applicants created after or equals to the input date.

Example: created_at.gte=2020-09-30 00:00:00.000Z
created_at.lte
string <timestamp>

Returns applicants created before or equals to the input date.

Example: created_at.lte=2022-09-30 00:00:00.000Z
hired_at.gte
string <timestamp>

Returns applicants hired after or equals to the input date.

Example: hired_at.gte=2022-09-30 00:00:00.000Z
hired_at.lte
string <timestamp>

Returns applicants hired before or equals to the input date.

Example: hired_at.lte=2022-09-30 00:00:00.000Z
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/position_applications
Request samples
Response samples
application/json
{
  • "data": [
    ]
}

Employees

Employees represent applicants who have been accepted into a new position, or people who are already working for your company.

Retrieve an existing Employee

Retrieves an existing Employee.

SecuritybearerAuth
Request
path Parameters
uuid
required
string <uuid>
query Parameters
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(information, address, emergency_contact, employment_details, work_location, compensation, direct_deposits, federal_tax, state_tax, eligibility, eligibility_details, custom_forms, position, location, department)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/employees/{uuid}
Request samples
Response samples
application/json
{
  • "uuid": "d404e957-af95-4776-af16-bae088e49165",
  • "first_name": "Ryan",
  • "middle_initial": "J",
  • "last_name": "Folk",
  • "start_date": "2019-08-24",
  • "applied_date": "2019-08-24",
  • "hired_date": "2019-08-24",
  • "onboard_date": "2019-08-24T14:15:22Z",
  • "status": "completed",
  • "information": {
    },
  • "address": {
    },
  • "emergency_contact": {
    },
  • "employment_details": {
    },
  • "work_location": {
    },
  • "compensation": {
    },
  • "direct_deposits": [
    ],
  • "federal_tax": {
    },
  • "state_tax": {
    },
  • "eligibility": {
    },
  • "eligibility_details": {
    },
  • "custom_forms": [
    ],
  • "position": {
    },
  • "location": {
    },
  • "department": {
    }
}

List existing employees

Lists existing employees with the input parameters.

SecuritybearerAuth
Request
query Parameters
first_name
string

Returns employees with the input first_name.

Example: first_name=Andy
last_name
string

Returns employees with the input last_name.

Example: last_name=Lee
onboarding_status
string

Returns employees with the input onboarding_status.

Enum: "not_started" "in_progress" "completed" "suspended"
Example: onboarding_status=completed
start_date.gte
string <date>

Returns employees with start_date after or equals to the input date.

Example: start_date.gte=2022-09-30
start_date.lte
string <date>

Returns employees with start_date before or equals to the input date.

Example: start_date.lte=2022-09-30
hired_date.gte
string <date>

Returns employees with hired_date after or equals to the input date.

Example: hired_date.gte=2022-09-30
hired_date.lte
string <date>

Returns employees with hired_date before or equals to the input date.

Example: hired_date.lte=2022-09-30
applied_date.gte
string <date>

Returns employees with applied_date after or equals to the input date.

Example: applied_date.gte=2022-09-30
applied_date.lte
string <date>

Returns employees with applied_date before or equals to the input date.

Example: applied_date.lte=2022-09-30
onboard_date.gte
string <timestamp>

Returns employees with onboard_date after or equals to the input date.

Example: onboard_date.gte=2022-09-30T00:00:00.000Z
onboard_date.lte
string <timestamp>

Returns employees with onboard_date before or equals to the input date.

Example: onboard_date.lte=2022-09-30T00:00:00.000Z
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(information, address, emergency_contact, employment_details, work_location, compensation, direct_deposits, federal_tax, state_tax, eligibility, custom_forms, position, location, department)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/employees
Request samples
Response samples
application/json
{
  • "data": [
    ]
}

Locations

Locations represent store locations within your company.

Retrieve an existing Location

Retrieves an existing Location.

SecuritybearerAuth
Request
path Parameters
uuid
required
string <uuid>
query Parameters
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(custom_fields)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/locations/{uuid}
Request samples
Response samples
application/json
{
  • "uuid": "8b9ad790-2584-11ee-be56-0242ac120002",
  • "name": "San Francisco store",
  • "custom_fields": [
    ]
}

List existing Locations

Lists existing Locations with the input parameters.

SecuritybearerAuth
Request
query Parameters
name
string

Returns locations with the input name.

Example: name=San Francisco
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(custom_fields)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/locations
Request samples
Response samples
application/json
{
  • "data": [
    ]
}

Departments

Departments represent departments within your company.

Retrieve an existing Department

Retrieves an existing Department.

SecuritybearerAuth
Request
path Parameters
uuid
required
string <uuid>
query Parameters
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(custom_fields)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/departments/{uuid}
Request samples
Response samples
application/json
{
  • "uuid": "77cac653-7150-4929-9fda-3ea0e33e108f",
  • "name": "Retail",
  • "custom_fields": [
    ]
}

List existing Departments

Lists existing Departments with the input parameters.

SecuritybearerAuth
Request
query Parameters
name
string

Returns departments with the input name.

Example: name=Retail
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(custom_fields)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/departments
Request samples
Response samples
application/json
{
  • "data": [
    ]
}

Team Members

Team Members represent team members that are managed within your company.

Retrieve an existing Team Member

Retrieves an existing Team Member.

SecuritybearerAuth
Request
path Parameters
uuid
required
string <uuid>
query Parameters
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(location, job_title, department, information, state_tax, federal_tax, eligibility, direct_deposits)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/team_members/{uuid}
Request samples
Response samples
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "first_name": "Ryan",
  • "middle_initial": "J",
  • "last_name": "Folk",
  • "termination_note": "string",
  • "start_date": "2019-08-24",
  • "status": "hired",
  • "job_title": {
    },
  • "location": {
    },
  • "department": {
    },
  • "information": {
    },
  • "direct_deposits": [
    ],
  • "state_tax": {
    },
  • "federal_tax": {
    },
  • "eligibility": {
    },
  • "custom_fields": [
    ]
}

Update an existing Team Member's status

Updates an existing Team Member's status.

SecuritybearerAuth
Request
path Parameters
uuid
required
string <uuid>
Request Body schema: application/json
status
string
Enum: "hired" "active" "offboarded"
last_day_of_work
string <date>

The last day of work. Required when updating a team member's status to offboarded.

note
string

The offboard note. Optional when updating a team member's status to offboarded.

rehireable
boolean

Whether the team member can be rehired. Optional when setting a team member's status to offboarded.

Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

put/team_members/{uuid}/status
Request samples
application/json
{
  • "status": "hired",
  • "last_day_of_work": "2019-08-24",
  • "note": "string",
  • "rehireable": true
}
Response samples
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "first_name": "Ryan",
  • "middle_initial": "J",
  • "last_name": "Folk",
  • "termination_note": "string",
  • "start_date": "2019-08-24",
  • "status": "hired"
}

List existing Team Members

Lists existing Team Members with the input parameters.

SecuritybearerAuth
Request
query Parameters
first_name
string

Returns team members with the input first_name.

Example: first_name=Andy
last_name
string

Returns team members with the input last_name.

Example: last_name=Lee
status
string

Returns team members with the input status.

Enum: "hired" "active" "offboarded"
location[uuid]
string <uuid>

Returns team members with the input location's UUID.

Example: location[uuid]=c59c9852-2584-11ee-be56-0242ac120002
job_title[title]
string

Returns team members with the input job_title's title.

Example: job_title[title]=Bus Driver
start_date.gte
string <date>

Returns team members with start_date after or equals to the input date.

Example: start_date.gte=2022-09-30
start_date.lte
string <date>

Returns team members with start_date before or equals to the input date.

Example: start_date.lte=2022-09-30
embed
string

Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.

Example: embed=(location, job_title, department, information, state_tax, federal_tax, eligibility, direct_deposits)
Responses
200

OK

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

get/team_members
Request samples
Response samples
application/json
{
  • "data": [
    ]
}

Create a new Team Member resource

Creates a new Team Member resource.

SecuritybearerAuth
Request
Request Body schema: application/json
object (Team Member Creation Payload)
Responses
201

Returns the newly created Team Member.

401

Unauthorized - Credentials are not valid for the target resource.

403

Forbidden - The user is not authorized to use this resource.

404

Not found - The requested resource is not found.

422

Unprocessable Entity - Invalid query params or request body.

429

Too many requests.

post/team_members
Request samples
application/json
{
  • "team_member": {
    }
}
Response samples
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}