logo

Workstream Public API (1.0.0)

Download OpenAPI specification:Download

E-mail: help@workstream.is URL: https://help.workstream.us/en/ License: Apache 2.0 Terms of Service

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" "company_users" "company_roles" "position_applications" "employees" "locations" "departments" "team_members" "imported_employee_infos"
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",
  • "job_url": "https://got.work/ryan_burgers_ryans_radical_rapping_teddy_bears/ad4b4e75",
  • "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": [
    ]
}
Company Users
Company Users represent people who are system users within your company.


List existing Company Users
Lists existing Company Users with the input parameters.


SecuritybearerAuth 
Request 
query Parameters
status
string
Returns Company users with the input status.


 Enum: "active" "disabled"  
 Example:  status=active
name
string
Returns Company Users with the input name.


 
 Example:  name=Joey
uuid
string <uuid> 
Returns the Company User with the input UUID.


 
 Example:  uuid=67161b3c-2584-11ee-be56-0242ac120002
created_at.gte
string <timestamp> 
Returns Company Users at or after the input date.


 
 Example:  created_at.gte=2020-09-30 00:00:00.000Z
created_at.lte
string <timestamp> 
Returns Company Users at or before the input date.


 
 Example:  created_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/company_users
Request samples 
Response samples 
application/json
{
  • "data": [
    ]
}
Create a new Company User with User info
Creates a new Company User with User info.


SecuritybearerAuth 
Request 
Request Body schema: application/json
required
object
 
name
required
string
Company User's full name.


 
company_role_uuid
required
string
Company Role's unique identifier.


 
region_number
string
 Default:  "1"
Contry code of Company User's phone number. Server will set it "1" as default if the request not set the parameter.


 
phone
string
Company User's phone number.


 
Responses 
201
Returns the newly created Company User.


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/company_users
Request samples 
application/json
{
  • "user": {
    },
  • "name": "Andy Lee",
  • "company_role_uuid": "c59c9852-2584-11ee-be56-0242ac120002",
  • "region_number": "1",
  • "phone": "7789882873"
}
Response samples 
application/json
{
  • "uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
  • "name": "Joey White",
  • "status": "active",
  • "region_number": "+1",
  • "phone": "4155693009",
  • "created_at": "2022-09-30T00:00:00.000Z",
  • "user": {
    },
  • "company_role": {
    },
  • "permission_config": {
    }
}
Update an existing Company User's Company Role & permissions
Update an existing Company User's Company Role & permissions.


SecuritybearerAuth 
Request 
path Parameters
uuid
required
string <uuid> 
 
 Example:  509a251a-93af-41e3-8416-23b29dc293cc
Request Body schema: application/json
company_role_uuid
string <uuid> 
Company Role's unique identifier.


 
object (permission_config) 
Location & Department Permission configuration.


 
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/company_users/{uuid}
Request samples 
application/json
{
  • "company_role_uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
  • "permission_config": {
    }
}
Response samples 
application/json
{
  • "uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
  • "name": "Joey White",
  • "status": "active",
  • "region_number": "+1",
  • "phone": "4155693009",
  • "created_at": "2022-09-30T00:00:00.000Z",
  • "user": {
    },
  • "company_role": {
    },
  • "permission_config": {
    }
}
Disable an active Company User
Disable an active Company User.


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.


post/company_users/{uuid}/disable
Request samples 
Response samples 
application/json
{
  • "uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
  • "status": "disabled"
}
Company Roles
Company Roles represent roles within your company.


List existing Company Roles
Lists existing Company Roles with the input parameters.


SecuritybearerAuth 
Request 
query Parameters
uuid
string <uuid> 
Returns the Company Role with the input UUID.


 
 Example:  uuid=67161b3c-2584-11ee-be56-0242ac120002
name
string
iReturns Company Roles with the input name.


 
 Example:  name=Joey
created_at.gte
string <timestamp> 
Returns Company Roles created at or after the input date.


 
 Example:  created_at.gte=2020-09-30 00:00:00.000Z
created_at.lte
string <timestamp> 
Returns Company Roles created at or after the input date.


 
 Example:  created_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/company_roles
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, pay_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",
  • "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": [
    ],
  • "pay_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.


Pagination. Send limit to get the results one page at a time, ordered by creation time. Each paginated response has has_more and next_cursor. To get the next page, repeat the request with the same filters and cursor set to next_cursor, until has_more is false.


Without limit or cursor, all matching applicants are returned in one response. For large result sets that response can be slow enough to time out, so use pagination. We recommend limit=500, which keeps the number of requests within the daily rate limit.


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, pay_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
limit
integer  [ 1 .. 500 ] 
 Default:  100
Returns at most this many applicants per page and turns on pagination. Values above 500 are treated as 500. Values that are missing, not a number or below 1 are treated as 100.


 
 Example:  limit=500
cursor
string
Returns the page after the one that gave this cursor. Pass next_cursor from the previous response unchanged, with the same filters. Sending cursor also turns on pagination. An invalid cursor returns 422 with error_code 13422.


 
 Example:  cursor=MTY3MDQ4NDU1MzcyOTg0NDoyMA
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": [
    ],
  • "count": 500,
  • "has_more": true,
  • "next_cursor": "MTY3MDQ4NDU1MzcyOTg0NDoyMA"
}
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",
  • "preferred_name": "Johnny",
  • "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": [
    ]
}
Retrieve an existing Employee (v2)
Retrieves an existing Employee. This endpoint is only available for companies that have been migrated to Workstream HRIS; companies that have not been migrated receive a 403 and should use GET /employees/{uuid} instead. Job assignments and earning rates are sourced from Workstream HRIS.


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. Permitted values: information, address, emergency_contact, company, job_assignments, location, department, custom_forms, direct_deposits, eligibility, eligibility_details, federal_tax, state_tax. The direct_deposits, federal_tax and state_tax embeds of employees paid through Workstream Payroll are read live from the payroll provider and carry a stricter rate limit than the rest of the API: a 429 with a Retry-After header means back off and retry after the indicated delay.


 
 Example:  embed=(information, address, emergency_contact, company, job_assignments, location)
Responses 
200
OK


401
Unauthorized - Credentials are not valid for the target resource.


403
Forbidden - The company has not been migrated to Workstream HRIS, or 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 - either the API's own request limit was reached, or data read live from Workstream Payroll (the direct_deposits, federal_tax and state_tax embeds of employees paid through Workstream Payroll) is temporarily rate limited. Back off and retry after the delay indicated by the Retry-After header.


503
Service Unavailable - a service this request depends on (Workstream HRIS, Workstream Payroll, or the tax withholding service) is temporarily unavailable. The request did not fail because of anything in it and is safe to retry.


get/v2/employees/{uuid}
Request samples 
Response samples 
application/json
{
  • "uuid": "d404e957-af95-4776-af16-bae088e49165",
  • "first_name": "Ryan",
  • "middle_initial": "J",
  • "last_name": "Folk",
  • "preferred_name": "Johnny",
  • "start_date": "2019-08-24",
  • "applied_date": "2019-08-24",
  • "hired_date": "2019-08-24",
  • "onboard_date": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "termination_date": "2019-08-24",
  • "termination_note": "string",
  • "information": {
    },
  • "address": {
    },
  • "emergency_contact": {
    },
  • "company": {
    },
  • "location": {
    },
  • "department": {
    },
  • "job_assignments": [
    ],
  • "custom_forms": [
    ],
  • "direct_deposits": [
    ],
  • "eligibility": {
    },
  • "eligibility_details": {
    },
  • "federal_tax": {
    },
  • "state_tax": [
    ]
}
List existing employees (v2)
Lists existing employees with the input parameters. This endpoint is only available for companies that have been migrated to Workstream HRIS; companies that have not been migrated receive a 403 and should use GET /employees instead. Job assignments and earning rates are sourced from Workstream HRIS.


SecuritybearerAuth 
Request 
query Parameters
status
string
Returns employees with the input status. Multiple statuses can be provided comma-separated. Permitted values: hired, onboarding, active, offboarded.


 
 Example:  status=active,onboarding
first_name
string
Returns employees with the input first_name (case-insensitive).


 
 Example:  first_name=Andy
last_name
string
Returns employees with the input last_name (case-insensitive).


 
 Example:  last_name=Lee
start_date.gt
string <date> 
Returns employees with start_date after the input date.


 
 Example:  start_date.gt=2022-09-30
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.lt
string <date> 
Returns employees with start_date before the input date.


 
 Example:  start_date.lt=2022-09-30
start_date.lte
string <date> 
Returns employees with start_date before or equals to the input date. A date-only value means through the end of that day.


 
 Example:  start_date.lte=2022-09-30
hired_date.gt
string <date> 
Returns employees with hired_date after the input date.


 
 Example:  hired_date.gt=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.lt
string <date> 
Returns employees with hired_date before the input date.


 
 Example:  hired_date.lt=2022-09-30
hired_date.lte
string <date> 
Returns employees with hired_date before or equals to the input date. A date-only value means through the end of that day.


 
 Example:  hired_date.lte=2022-09-30
applied_date.gt
string <date> 
Returns employees with applied_date after the input date.


 
 Example:  applied_date.gt=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.lt
string <date> 
Returns employees with applied_date before the input date.


 
 Example:  applied_date.lt=2022-09-30
applied_date.lte
string <date> 
Returns employees with applied_date before or equals to the input date. A date-only value means through the end of that day.


 
 Example:  applied_date.lte=2022-09-30
onboard_date.gt
string <date> 
Returns employees with onboard_date after the input date.


 
 Example:  onboard_date.gt=2022-09-30
onboard_date.gte
string <date> 
Returns employees with onboard_date after or equals to the input date.


 
 Example:  onboard_date.gte=2022-09-30
onboard_date.lt
string <date> 
Returns employees with onboard_date before the input date.


 
 Example:  onboard_date.lt=2022-09-30
onboard_date.lte
string <date> 
Returns employees with onboard_date before or equals to the input date. A date-only value means through the end of that day.


 
 Example:  onboard_date.lte=2022-09-30
termination_date.gt
string <date> 
Returns employees with termination_date after the input date.


 
 Example:  termination_date.gt=2022-09-30
termination_date.gte
string <date> 
Returns employees with termination_date after or equals to the input date.


 
 Example:  termination_date.gte=2022-09-30
termination_date.lt
string <date> 
Returns employees with termination_date before the input date.


 
 Example:  termination_date.lt=2022-09-30
termination_date.lte
string <date> 
Returns employees with termination_date before or equals to the input date. A date-only value means through the end of that day.


 
 Example:  termination_date.lte=2022-09-30
page
integer
Page number to return.


 
 Example:  page=1
per_page
integer  <= 100 
 Default:  25
Number of employees per page. Defaults to 25, maximum 100.


 
 Example:  per_page=25
embed
string
Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated. Permitted values: information, address, emergency_contact, company, job_assignments, location, department, custom_forms, direct_deposits, eligibility, eligibility_details. federal_tax and state_tax are only available on GET /v2/employees/{uuid}; requesting them here returns a 422. Note that on this list endpoint, direct_deposits of employees paid through Workstream Payroll carry no net pay split fields — use GET /v2/employees/{uuid} for the full detail.


 
 Example:  embed=(information, address, emergency_contact, company, job_assignments, location)
Responses 
200
OK


401
Unauthorized - Credentials are not valid for the target resource.


403
Forbidden - The company has not been migrated to Workstream HRIS, or the user is not authorized to use this resource.


422
Unprocessable Entity - Invalid query params or request body.


429
Too Many Requests - either the API's own request limit was reached, or data read live from Workstream Payroll (the direct_deposits embed of employees paid through Workstream Payroll) is temporarily rate limited. Back off and retry after the delay indicated by the Retry-After header.


503
Service Unavailable - a service this request depends on (Workstream HRIS, Workstream Payroll, or the tax withholding service) is temporarily unavailable. The request did not fail because of anything in it and is safe to retry.


get/v2/employees
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}
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",
  • "preferred_name": "Johnny",
  • "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",
  • "preferred_name": "Johnny",
  • "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"
}
Employee Documents
Employee Documents represent documents that are associated with employees within your company.


Download a employee document
Download employee document with document id.
Note: This endpoint requires the document-public-api feature flag. Please contact our support team to request access.


Request 
path Parameters
document_id
required
string
The document id to download the file.


 
 Example:  123e4567-e89b-12d3-a456-426614174000
query Parameters
token
string
The authorization token to access the document.


 
 Example:  token=token123
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/employee/docs/{document_id}
Request samples 
Response samples 
application/problem+json
{
  • "error_code": 13401,
  • "message": "Unauthorized"
}
List existing Employee Documents
Lists existing employee documents with the input parameters.
Note: This endpoint requires the document-public-api feature flag. Please contact our support team to request access.


SecuritybearerAuth 
Request 
query Parameters
employee_uuid
string
Returns employee docs with the input employee_uuid.


 
 Example:  employee_uuid=123e4567-e89b-12d3-a456-426614174000
first_name
string
Returns employee docs with the input first_name.


 
 Example:  first_name=Andy
last_name
string
Returns employee docs with the input last_name.


 
 Example:  last_name=Lee
onboarding_status
string
Returns employee docs with the input onboarding_status.


 Enum: "not_started" "in_progress" "completed" "suspended"  
 Example:  onboarding_status=completed
start_date.gte
string <date> 
Returns employee docs with start_date after or equals to the input date.


 
 Example:  start_date.gte=2022-09-30
start_date.lte
string <date> 
Returns employee docs with start_date before or equals to the input date.


 
 Example:  start_date.lte=2022-09-30
hired_date.gte
string <date> 
Returns employee docs with hired_date after or equals to the input date.


 
 Example:  hired_date.gte=2022-09-30
hired_date.lte
string <date> 
Returns employee docs with hired_date before or equals to the input date.


 
 Example:  hired_date.lte=2022-09-30
applied_date.gte
string <date> 
Returns employee docs with applied_date after or equals to the input date.


 
 Example:  applied_date.gte=2022-09-30
applied_date.lte
string <date> 
Returns employee docs with applied_date before or equals to the input date.


 
 Example:  applied_date.lte=2022-09-30
onboard_date.gte
string <timestamp> 
Returns employee docs 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 employee docs 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 document types that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.


 
 Example:  embed=(w4_doc, state_tax_docs, i9_docs, company_docs)
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/employee/docs
Request samples 
Response samples 
application/json
{
  • "data": []
}
Imported Employee Infos
Imported Employee Infos represent imported employee information that is associated with employees within your company.


List existing Imported Employee Infos
List existing Imported Employee Infos


SecuritybearerAuth 
Request 
query Parameters
page
integer
The page number to retrieve.


 
 Example:  page=1
per_page
integer
The number of items to retrieve per page, maximum is 100.


 
 Example:  per_page=10
Responses 
200
Returns the imported employee info list.


401
Unauthorized - Credentials are not valid for the target resource.


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


422
Unprocessable Entity - Invalid query params or request body.


429
Too many requests.


get/imported_employee_infos
Request samples 
Response samples 
application/json
{
  • "imported_employee_infos": [
    ]
}
Custom Field
Custom field config for location, department, job posting, employee and job within your company.


List existing Custom Fields
List existing Custom Fields


SecuritybearerAuth 
Request 
query Parameters
entity_type
string
Entity type of the custom field.


 Enum: "location" "department" "job_posting_template" "employee_record" "job"  
Responses 
200
Returns all custom field values for an entity


401
Unauthorized - Credentials are not valid for the target resource.


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


422
Unprocessable Entity - Invalid query params or request body.


429
Too many requests.


get/custom_fields
Request samples 
Response samples 
application/json
{
  • "custom_fields": [
    ]
}
Create Custom Field
Create Custom Field


SecuritybearerAuth 
Request 
Request Body schema: application/json
required
object
Custom field create or update content


 
Responses 
200
Returns new created custom field


401
Unauthorized - Credentials are not valid for the target resource.


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


422
Unprocessable Entity - Invalid query params or request body.


429
Too many requests.


post/custom_fields
Request samples 
application/json
{
  • "custom_field": {
    }
}
Response samples 
application/json
{
  • "custom_field": {
    }
}
Update an existing Custom Field
Update an existing Custom Field


SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
 
 Example:  509a251a-93af-41e3-8416-23b29dc293cc
Request Body schema: application/json
object
Custom field create or update content


 
Responses 
200
Update a custom field successfully


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/custom_fields/{id}
Request samples 
application/json
{
  • "custom_field": {
    }
}
Response samples 
application/json
{
  • "custom_field": {
    }
}
Create or update custom field value
Create or update the custom field values of one entity. A non-empty
custom_field_values replaces the entity's whole value list: a field left out
of it is cleared. A request with a missing or empty custom_field_values
changes nothing. To clear one field, send the full list with that field's
value empty.


For job, entity_id is the HRIS job id, as returned in
job_assignments[].job_id (for example job_01h46z1k2cf2av8mp4r7we4697).
For location, department and employee_record it is the entity uuid.
job_posting_template is not supported on this endpoint yet. For job, the job is checked
with Workstream HRIS, so the request returns 503 if HRIS is unavailable.


SecuritybearerAuth 
Request 
path Parameters
entity_type
required
string
Entity type of custom field value.


 Enum: "location" "department" "job_posting_template" "employee_record" "job"  
entity_id
required
string
Entity uuid, or the HRIS job id when entity_type is job (job_posting_template is not supported yet)


 
 Example:  job_01h46z1k2cf2av8mp4r7we4697
Request Body schema: application/json
required
Array of objects
Custom field values of entity


 
Responses 
200
Returns new created custom field


400
Bad request. error_code is 40060 for an invalid entity_type. For job,
value errors return 40000 (bad body), 40061 (required field blank), 40062
(invalid value format) or 40063 (field is not a job field of this company).
For the other entity types, value errors return 50000 with the joined messages.


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.


503
Service Unavailable - a service this request depends on (Workstream HRIS, Workstream Payroll, or the tax withholding service) is temporarily unavailable. The request did not fail because of anything in it and is safe to retry.


put/entity_type/{entity_type}/entity_id/{entity_id}/custom_field_values
Request samples 
application/json
{
  • "custom_field_values": [
    ]
}
Response samples 
application/json
{
  • "entity_id": "string",
  • "entity_type": "string",
  • "custom_field_value": [
    ]
}