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

401

Unauthorized

post/tokens

Request samples

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"name": "token1",
"token": "OtrQV4Gz7nwLouCm-ZLqiSxdwJEMEAFGx___GcNxES8",
"created_at": "2019-08-24T14:15:22Z",
"expires_in": 604800,
"scopes": ["positions",
"company_users",
"company_roles",
"position_applications",
"employees",
"locations",
"departments",
"team_members",
"imported_employee_infos"
]
}

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

401

Unauthorized

post/tokens/refresh_token

Request samples

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"name": "token1",
"token": "OtrQV4Gz7nwLouCm-ZLqiSxdwJEMEAFGx___GcNxES8",
"created_at": "2019-08-24T14:15:22Z",
"expires_in": 604800,
"scopes": ["positions",
"company_users",
"company_roles",
"position_applications",
"employees",
"locations",
"departments",
"team_members",
"imported_employee_infos"
]
}

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

403

Unauthorized Client

post/revoke

Request samples

curl
JavaScript
PHP
Ruby
Python

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

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

curl
JavaScript
PHP
Ruby
Python

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": {"uuid": "fc4487ce-67n0-436e-9aa7-a2eb496aff0e",
"name": "SF store",
"address": "string",
"postal_code": "string",
"city": "string",
"state": "string",
"country": "string"
},
"custom_fields": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"title": "custom field title",
"value": "custom field value"
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"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": {"uuid": "fc4487ce-67n0-436e-9aa7-a2eb496aff0e",
"name": "SF store",
"address": "string",
"postal_code": "string",
"city": "string",
"state": "string",
"country": "string"
},
"custom_fields": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"title": "custom field title",
"value": "custom field value"
}
]
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"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": {"email": "test@test.com",
"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"created_at": "2022-09-30T00:00:00.000Z"
},
"company_role": {"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"name": "General Manager",
"editable": true,
"permissions_set": ["edit_user edit_location",
"edit_department",
"customize_notifications",
"edit_position",
"edit_custom_reports",
"edit_custom_field",
"edit_integration",
"edit_company"
],
"created_at": "2022-09-30T00:00:00.000Z"
},
"permission_config": {"all_locations": false,
"locations": [{"uuid": "67161b3c-2584-11ee-be56-0242ac120002",
"all_departments": false,
"departments": [{"uuid": null
}
]
}
]
}
}
]
}

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": {"email": "test@test.com",
"password": "password"
},
"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": {"email": "test@test.com",
"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"created_at": "2022-09-30T00:00:00.000Z"
},
"company_role": {"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"name": "General Manager",
"editable": true,
"permissions_set": ["edit_user edit_location",
"edit_department",
"customize_notifications",
"edit_position",
"edit_custom_reports",
"edit_custom_field",
"edit_integration",
"edit_company"
],
"created_at": "2022-09-30T00:00:00.000Z"
},
"permission_config": {"all_locations": false,
"locations": [{"uuid": "67161b3c-2584-11ee-be56-0242ac120002",
"all_departments": false,
"departments": [{"uuid": "47161b3c-2584-11ee-be56-0242ac120002"
}
]
}
]
}
}

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

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": {"all_locations": false,
"locations": [{"uuid": "67161b3c-2584-11ee-be56-0242ac120002",
"all_departments": false,
"departments": [{"uuid": "47161b3c-2584-11ee-be56-0242ac120002"
}
]
}
]
}
}

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": {"email": "test@test.com",
"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"created_at": "2022-09-30T00:00:00.000Z"
},
"company_role": {"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"name": "General Manager",
"editable": true,
"permissions_set": ["edit_user edit_location",
"edit_department",
"customize_notifications",
"edit_position",
"edit_custom_reports",
"edit_custom_field",
"edit_integration",
"edit_company"
],
"created_at": "2022-09-30T00:00:00.000Z"
},
"permission_config": {"all_locations": false,
"locations": [{"uuid": "67161b3c-2584-11ee-be56-0242ac120002",
"all_departments": false,
"departments": [{"uuid": "47161b3c-2584-11ee-be56-0242ac120002"
}
]
}
]
}
}

Disable an active Company User

Disable an active Company User.

SecuritybearerAuth

Request

path Parameters

uuid

required

string <uuid>

Responses

200

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

curl
JavaScript
PHP
Ruby
Python

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"name": "General Manager",
"editable": true,
"permissions_set": ["edit_user edit_location",
"edit_department",
"customize_notifications",
"edit_position",
"edit_custom_reports",
"edit_custom_field",
"edit_integration",
"edit_company"
],
"created_at": "2022-09-30T00:00:00.000Z"
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

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": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"title": "Cook"
},
"location": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "SF store"
},
"department": {"name": "Marketing",
"description": "The marketing department"
},
"notes": [{"content": "He is a good applicant!"
}
],
"tags": [{"name": "cook"
}
],
"candidate_info": [{"question": "Street Address",
"answer": "110 W 5 st"
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"uuid": "d404e957-af95-4776-af16-bae088e49165",
"name": "Additional Information",
"answers": [{"question_uuid": "d404e957-af95-4776-af16-bae088e49165",
"question_type": "multiple_choice",
"question": "Are you at least 18 years old with a valid Driver's license?",
"answer_uuid": "d404e957-af95-4776-af16-bae088e49165",
"answer": "yes"
}
]
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"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": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"title": "Cook"
},
"location": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "SF store"
},
"department": {"name": "Marketing",
"description": "The marketing department"
},
"notes": [{"content": "He is a good applicant!"
}
],
"tags": [{"name": "cook"
}
],
"candidate_info": [{"question": "Street Address",
"answer": "110 W 5 st"
}
]
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

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": {"phone": "+17789882873",
"email": "wadam@example.fr",
"birthday": "2019-08-24",
"ethnicity": "black_or_african_american",
"gender": "male",
"ssn": "0015594",
"marital_status": "never_married"
},
"address": {"address": "6488 Gateway dr",
"city": "Washington",
"state": "United States",
"country": "Virginia",
"zipcode": "23703"
},
"emergency_contact": {"name": "Melinda Folk",
"email": "folk@example.fr",
"phone": "+16084559135",
"relationship": "Father"
},
"employment_details": {"applied_date": "2019-08-24",
"department_name": "Staff",
"hired_date": "2019-08-24",
"job_title": "Barista",
"manager": "Test Manager",
"start_date": "2019-08-24"
},
"work_location": {"name": "Store",
"address": "800 Kings Way",
"city": "Vancouver",
"state": "VA",
"country": "US",
"zipcode": "23321"
},
"compensation": {"additional_remuneration": "2",
"additional_remuneration_currency_code": "USD",
"employment_status": "full_time",
"status": "non_exempt",
"wage_amount": "12",
"wage_currency_code": "USD",
"wage_pay_frequency": "hour"
},
"direct_deposits": [{"account_number": "112223344",
"account_type": "saving",
"percentage": 0,
"routing_number": "00356",
"status": "active"
}
],
"federal_tax": {"deductions": 0,
"extra_withholding": 0,
"filing_status": "string",
"other_income": 0,
"qualifying_children_num": 0,
"qualifying_other_num": 0,
"dependents": 0,
"two_jobs": true,
"exempt_from_withholding": "string"
},
"state_tax": {"allowances_exemptions": 0,
"extra_withholding": 0,
"filing_status": "string",
"tax_form": "string",
"state": "string",
"tax_form_details": { }
},
"eligibility": {"admission_number": "string",
"alien_authorized_to_work_expiration_date": "2019-08-24",
"alien_registration_or_uscis_number": "string",
"country_of_issuance": "string",
"lawful_permanent_resident_alien_registration_or_uscis_number": 0,
"passport_number": "string",
"resident_status_code": "string",
"social_security_number": "string"
},
"eligibility_details": {"i9_section_one": {"admission_number": "string",
"alien_authorized_to_work_expiration_date": "2019-08-24",
"alien_registration_or_uscis_number": "string",
"country_of_issuance": "string",
"lawful_permanent_resident_alien_registration_or_uscis_number": 0,
"passport_number": "string",
"resident_status_code": "string",
"social_security_number": "string",
"employee_signed_date": "2019-08-24"
},
"i9_section_two": {"employer_fname": "string",
"employer_lname": "string",
"employer_job_title": "string",
"employee_start_date": "string",
"employer_signed_date": "2019-08-24",
"list_a": {"list_a_document_title_1": "string",
"list_a_document_number_1": "string",
"list_a_expiration_date_1": "2019-08-24",
"list_a_no_expiration_date_1": true,
"list_a_issuing_authority_1": "string",
"list_a_document_title_2": "string",
"list_a_document_number_2": "string",
"list_a_expiration_date_2": "2019-08-24",
"list_a_no_expiration_date_2": true,
"list_a_issuing_authority_2": "string",
"list_a_document_title_3": "string",
"list_a_document_number_3": "string",
"list_a_expiration_date_3": "2019-08-24",
"list_a_no_expiration_date_3": true,
"list_a_issuing_authority_3": "string"
},
"list_b": {"list_b_document_title_1": "string",
"list_b_document_code": "string",
"list_b_document_number_1": "string",
"list_b_issuing_authority_1": "string",
"list_b_us_state_code_1": "CA",
"list_b_expiration_date_1": "2019-08-24",
"list_b_no_expiration_date": true
},
"list_c": {"list_c_document_title_1": "string",
"list_c_document_code": "string",
"list_c_issuing_authority_1": "string",
"list_c_document_number_1": "string",
"list_c_expiration_date_1": "2019-08-24",
"list_c_no_expiration_date": true
}
}
},
"custom_forms": [{"name": "Custom form",
"content": [{"question": {"title": "How old are you?",
"content": "Please enter your age."
},
"answer": [{ }
]
}
]
}
],
"position": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"title": "Cook"
},
"location": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "SF store"
},
"department": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "Marketing"
}
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"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": {"phone": "+17789882873",
"email": "wadam@example.fr",
"birthday": "2019-08-24",
"ethnicity": "black_or_african_american",
"gender": "male",
"ssn": "0015594",
"marital_status": "never_married"
},
"address": {"address": "6488 Gateway dr",
"city": "Washington",
"state": "United States",
"country": "Virginia",
"zipcode": "23703"
},
"emergency_contact": {"name": "Melinda Folk",
"email": "folk@example.fr",
"phone": "+16084559135",
"relationship": "Father"
},
"employment_details": {"applied_date": "2019-08-24",
"department_name": "Staff",
"hired_date": "2019-08-24",
"job_title": "Barista",
"manager": "Test Manager",
"start_date": "2019-08-24"
},
"work_location": {"name": "Store",
"address": "800 Kings Way",
"city": "Vancouver",
"state": "VA",
"country": "US",
"zipcode": "23321"
},
"compensation": {"additional_remuneration": "2",
"additional_remuneration_currency_code": "USD",
"employment_status": "full_time",
"status": "non_exempt",
"wage_amount": "12",
"wage_currency_code": "USD",
"wage_pay_frequency": "hour"
},
"direct_deposits": [{"account_number": "112223344",
"account_type": "saving",
"percentage": 0,
"routing_number": "00356",
"status": "active"
}
],
"federal_tax": {"deductions": 0,
"extra_withholding": 0,
"filing_status": "string",
"other_income": 0,
"qualifying_children_num": 0,
"qualifying_other_num": 0,
"dependents": 0,
"two_jobs": true,
"exempt_from_withholding": "string"
},
"state_tax": {"allowances_exemptions": 0,
"extra_withholding": 0,
"filing_status": "string",
"tax_form": "string",
"state": "string",
"tax_form_details": { }
},
"eligibility": {"admission_number": "string",
"alien_authorized_to_work_expiration_date": "2019-08-24",
"alien_registration_or_uscis_number": "string",
"country_of_issuance": "string",
"lawful_permanent_resident_alien_registration_or_uscis_number": 0,
"passport_number": "string",
"resident_status_code": "string",
"social_security_number": "string"
},
"eligibility_details": {"i9_section_one": {"admission_number": "string",
"alien_authorized_to_work_expiration_date": "2019-08-24",
"alien_registration_or_uscis_number": "string",
"country_of_issuance": "string",
"lawful_permanent_resident_alien_registration_or_uscis_number": 0,
"passport_number": "string",
"resident_status_code": "string",
"social_security_number": "string",
"employee_signed_date": "2019-08-24"
},
"i9_section_two": {"employer_fname": "string",
"employer_lname": "string",
"employer_job_title": "string",
"employee_start_date": "string",
"employer_signed_date": "2019-08-24",
"list_a": {"list_a_document_title_1": "string",
"list_a_document_number_1": "string",
"list_a_expiration_date_1": "2019-08-24",
"list_a_no_expiration_date_1": true,
"list_a_issuing_authority_1": "string",
"list_a_document_title_2": "string",
"list_a_document_number_2": "string",
"list_a_expiration_date_2": "2019-08-24",
"list_a_no_expiration_date_2": true,
"list_a_issuing_authority_2": "string",
"list_a_document_title_3": "string",
"list_a_document_number_3": "string",
"list_a_expiration_date_3": "2019-08-24",
"list_a_no_expiration_date_3": true,
"list_a_issuing_authority_3": "string"
},
"list_b": {"list_b_document_title_1": "string",
"list_b_document_code": "string",
"list_b_document_number_1": "string",
"list_b_issuing_authority_1": "string",
"list_b_us_state_code_1": "CA",
"list_b_expiration_date_1": "2019-08-24",
"list_b_no_expiration_date": true
},
"list_c": {"list_c_document_title_1": "string",
"list_c_document_code": "string",
"list_c_issuing_authority_1": "string",
"list_c_document_number_1": "string",
"list_c_expiration_date_1": "2019-08-24",
"list_c_no_expiration_date": true
}
}
},
"custom_forms": [{"name": "Custom form",
"content": [{"question": {"title": null,
"content": null
},
"answer": [{ }
]
}
]
}
],
"position": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"title": "Cook"
},
"location": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "SF store"
},
"department": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "Marketing"
}
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"uuid": "8b9ad790-2584-11ee-be56-0242ac120002",
"name": "San Francisco store",
"custom_fields": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"title": "custom field title",
"value": "custom field value"
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"uuid": "8b9ad790-2584-11ee-be56-0242ac120002",
"name": "San Francisco store",
"custom_fields": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"title": "custom field title",
"value": "custom field value"
}
]
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"uuid": "77cac653-7150-4929-9fda-3ea0e33e108f",
"name": "Retail",
"custom_fields": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"title": "custom field title",
"value": "custom field value"
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"uuid": "77cac653-7150-4929-9fda-3ea0e33e108f",
"name": "Retail",
"custom_fields": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"title": "custom field title",
"value": "custom field value"
}
]
}
]
}

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

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

curl
JavaScript
PHP
Ruby
Python

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": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"title": "Bus Driver"
},
"location": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "SF store"
},
"department": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "Marketing"
},
"information": {"phone": "+17789882873",
"email": "wadam@example.fr",
"dob": "2020-04-01",
"ethnicity": "black_or_african_american",
"gender": "male",
"ssn": "222521248",
"marital_status": "never_married"
},
"direct_deposits": [{"account_number": "112223344",
"account_type": "saving",
"percentage": 0,
"routing_number": "00356",
"status": "active"
}
],
"state_tax": {"allowances_exemptions": 0,
"extra_withholding": 0,
"filing_status": "string",
"tax_form": "string",
"state": "string",
"tax_form_details": { }
},
"federal_tax": {"deductions": 0,
"extra_withholding": 0,
"filing_status": "string",
"other_income": 0,
"qualifying_children_num": 0,
"qualifying_other_num": 0,
"two_jobs": true
},
"eligibility": {"allowances_exemptions": 0,
"extra_withholding": 0,
"filing_status": "string",
"tax_form": "string"
},
"custom_fields": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"title": "custom field title",
"value": "custom field value"
}
]
}

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

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"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": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"title": "Bus Driver"
},
"location": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "SF store"
},
"department": {"uuid": "c59c9852-2584-11ee-be56-0242ac120002",
"name": "Marketing"
},
"information": {"phone": "+17789882873",
"email": "wadam@example.fr",
"dob": "2020-04-01",
"ethnicity": "black_or_african_american",
"gender": "male",
"ssn": "222521248",
"marital_status": "never_married"
},
"direct_deposits": [{"account_number": "112223344",
"account_type": "saving",
"percentage": 0,
"routing_number": "00356",
"status": "active"
}
],
"state_tax": {"allowances_exemptions": 0,
"extra_withholding": 0,
"filing_status": "string",
"tax_form": "string",
"state": "string",
"tax_form_details": { }
},
"federal_tax": {"deductions": 0,
"extra_withholding": 0,
"filing_status": "string",
"other_income": 0,
"qualifying_children_num": 0,
"qualifying_other_num": 0,
"two_jobs": true
},
"eligibility": {"allowances_exemptions": 0,
"extra_withholding": 0,
"filing_status": "string",
"tax_form": "string"
},
"custom_fields": [{"uuid": "509a251a-93af-41e3-8416-23b29dc293cc",
"title": "custom field title",
"value": "custom field value"
}
]
}
]
}

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": {"first_name": "Ryan",
"middle_initial": "J",
"last_name": "Folk",
"dob": "2020-04-01",
"phone": "+17789882873",
"email": "wadam@example.fr",
"gender": "male",
"status": "hired",
"start_date": "2023-05-01",
"location": {"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
},
"job_title": {"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
},
"department": {"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
},
"government_ids": [{"type": "SSN",
"value": "222521248"
}
],
"metadata": { }
}
}

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

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

curl
JavaScript
PHP
Ruby
Python

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

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"data": [{"employee_uuid": "d404e957-af95-4776-af16-bae088e49165",
"documents": [{"url": "https://example.com/employee/docs/123",
"type": "w4",
"created_at": "2022-09-30T00:00:00.000Z"
}
]
}
]
}

Imported Employee Infos

Imported Employee Infos represent imported employee information that is associated with employees within your company.

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

curl
JavaScript
PHP
Ruby
Python

Response samples

application/json

{"imported_employee_infos": [{"first_name": "Tom",
"last_name": "string",
"phone": "+17789882873",
"email": "string",
"rehire_eligiblity": "eligible",
"termination_reason": "string"
}
]
}