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.


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
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"
}
Employee Documents
Employee Documents represent documents that are associated with employees within your company.


Download a employee document
Download employee document with document id.


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.


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 and employee 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"  
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.


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 custom field value


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


 Enum: "location" "department" "job_posting_template" "employee_record"  
entity_id
required
integer
Entity id of custom field value


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


 
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.


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": 0,
  • "entity_type": "string",
  • "custom_field_values": [
    ]
}