Introduction

Welcome use Workstream API interface. You can use HTTP request access Workstream service.

Workstream API follow RESTful style. All API URLs are https://public-api.workstream.us/<api path>/

Successful responses have HTTP status code (2xx), if reponse failed, you can get detail json message.

Concepts

Position

Your company has some positions, Position is a core concept of Workstream system.

Position object attributes

attribute	type	description
digest_key	string	unique id
title	string	position title
overview	string	position summary
status	string	positions status, includes `pending`, `published`, `closed`, `deleted`, and `cache`
access	string	Only allow link to access position (`link_only`) or allow career page and job board access position (`public`).
number	string	position serial number
pay_amount	string	salary
pay_frequency	string	pay salary frequency
job_type	string	`full_time`, `part_time`, `contract`, `internship`, `comission` or others
normalized_titles	string	normalized position title
remote_type	string	position is remote work or not, includes on_site, fully_remote, flexible_remote, temporarily_remote.

Position Application

Means applicant, one position has some applicats. Applicant is a core concept of Workstream system.

Position Application object attributes

attribute	type	default	description
digest_key	string		unique id
referer_source	string		Which source from applicant apply.
email	string		applicant email.
phone	string		applicant phone number.
first_name	string		applicant first name.
last_name	string		applicant last name.
name	string		applicant full name.
status	string		applicant status, includes `in_process`, `hired`, `rejected`
phone_verified_at	string		applicant phone verified datetime
sms_phone_number	string		phone number which applicant receive sms
global_phone_number	string		applicant phone number and inlcludes region code
sms_notification	boolean	true	allow applicant receive sms notification

Authorization

Workstream supply standard Oauth2 network protocal, allow user manage data by HTTP API request. Before you send HTTP API request, you need to get authorized token.

If your company already open Oauth App function module, you can get client_id ，client_secret in your setting page (https://hr.workstream.us/#/account?currentPanel=accesstoken).

If not, you can call customer service and ask opening Oauth App function module.

After it, if you don’t have access token, you can click Generate token, and add token to HTTP header Authoization. Auch as right codes:

curl --request GET 'https://public-api.workstream.us/positions'
--header 'Authorization: Bearer 5irTQaUs4xBPyEyVtkPzHWo1jxaz_kOam5OalD1cun4'

Also, you can manage access token by token API, too.

attribute	description
client_id	Client access identification, only super admin can access it.
client_secret	Password of client id, use to generate and revoke access token.
access_token	When client want to access 3th-party Workstream service, attach access_token in HTTP header as `Authorization: Bearer <token>`, and invoke Workstream Oauth API. Access token has 6 months active time, after that token will expired.

Create access token

POST /tokens

HTTP Parameters

param	type	default	required	description
grant_type	string	client_credentials	yes	grant type of access token, please use `client_credentials`
client_id	string		yes	client access identification
client_secret	string		yes	password of client access identification
name	string		no	name of your token
scopes	array		no	permissions of access token, can choose from: `positions`, `position_applications`, `employees`

Response

JSON format Access Token

{
    "access_token": "AqrqBVwadstAdr_Ens0j5iHLug3gVKkOnTnDXvSDhmo",
    "token_type": "Bearer",
    "created_at": 1614659544,
    "name": "token name",
    "scopes": ["positions", "position_applications", "employees"]
}

Revoke access token

POST /revoke

HTTP Parameters

param	type	required	description
client_id	string	yes	client access identification
client_scret	string	yes	password of client access identification
token	string	yes	specify access token value

Response

JSON format blank object

{}

Position

Position object

Get All positions

HTTP Request

GET /positions

HTTP Parameters

param	type	required	description
access_token	Bearer Token	yes	HTTP header Authorization Bearer token
start_datetime	string	no	filter positions after their created datetime. For example `2020-01-30 00:00:00`
end_datetime	string	no	filter positions before their created datetime. For example `2020-12-30 23:59:59`
status	string	no	filter positions by status, includes `pending`, `published`, `closed`, `deleted` and `cache`
access	string	no	filter positions by access, includes `link_only`, `public`
title	string	no	filter positions by title
location_name	string	no	filter positions by their location’s name

Response

JSON format Position objects array

{
    "positions": [
        {
            "digest_key": "e1d1ad31",
            "title": "Customer Success Associate",
            "overview": "We are looking for a full-time, dedicated, and passionate individual to join our growing team.",
            "status": "cache",
            "number": "1845",
            "access": "public",
            "pay_amount": null,
            "pay_frequency": null,
            "job_type": null,
            "normalized_titles": null,
            "remote_type": "on_site",
            "job_url": "https://got.work/ryan_burgers_ryans_radical_rapping_teddy_bears/ad4b4e75",
            "location": {
                "digest_key": "eca510e7",
                "name": "Apple Park 15",
                "address": "6488 Gateway dr",
                "postal_code": "23703",
                "city": "Washington",
                "state": "Virginia",
                "country": "US"
            }
        },
        {
            "digest_key": "4662ec5e26d336cfedc8f475a2ea7a64373a9d33",
            "title": "Software Engineer",
            "overview": "Do software stuff",
            "status": "cache",
            "number": "9348",
            "access": "public",
            "pay_amount": null,
            "pay_frequency": null,
            "job_type": null,
            "normalized_titles": null,
            "remote_type": "on_site",
            "job_url": "https://got.work/ryan_burgers_ryans_radical_rapping_teddy_bears/ad4b4e75",
            "location": {
                "digest_key": "eca510e7",
                "name": "Apple Park 15",
                "address": "6488 Gateway dr",
                "postal_code": "23703",
                "city": "Washington",
                "state": "Virginia",
                "country": "US"
            }
        }
    ],
     "count": 2
}

Get the position by digest_key

HTTP Request

GET /positions/:digest_key

HTTP Parameters

param	type	default	required	descrpition
access_token	Bearer Token		yes	HTTP header Authorization Bearer token

Response

JSON format Position object

{
  "position": {
      "digest_key": "e1d1ad31",
      "title": "Customer Success Associate",
      "overview": "We are looking for a full-time, dedicated, and passionate individual to join our growing team.",
      "status": "cache",
      "number": "1845",
      "access": "public",
      "pay_amount": null,
      "pay_frequency": null,
      "job_type": null,
      "normalized_titles": null,
      "remote_type": "on_site",
      "job_url": "https://got.work/ryan_burgers_ryans_radical_rapping_teddy_bears/ad4b4e75",
      "location": {
          "digest_key": "eca510e7",
          "name": "Apple Park 15",
          "address": "6488 Gateway dr",
          "postal_code": "23703",
          "city": "Washington",
          "state": "Virginia",
          "country": "US"
      }
  }
}

Applicant

PositionApplication object

Get All applicants

HTTP Request

GET /position_applications

HTTP Parameters

param	type	required	description
access_token	Bearer Token	yes	HTTP header Authorization Bearer token
start_datetime	string	no	filter applicants after their created datetime. For example `2020-01-30 00:00:00`
end_datetime	string	no	filter applicants before their created datetime. For example `2020-12-30 23:59:59`
min_hired_at	string	no	filter applicants after their hired_at datetime. For example `2020-01-30 00:00:00`
max_hired_at	string	no	filter applicants before their hired_at datetime. For example `2020-12-30 23:59:59`
status	string	no	filter applicatns by status, includes `in_process`, `hired`, `rejected`
first_name	string	no	filter applicants by first name
last_name	string	no	filter applicants by last name
name	string	no	filter applicants by name
position_digest_key	string	no	filter applicants by position’s digest key.
location_name	string	no	filter positions by their location’s name
current_stage	string	no	filter applicants by the current stage of the application

Response

JSON format PositionApplication objects array

{
  "position_applications": [
      {
          "digest_key": "108eeee1",
          "referer_source": "Angelist",
          "email": "angelistxxx@gmail.com",
          "phone": "4321012345",
          "first_name": "Joey",
          "last_name": "White",
          "name": "Joey White",
          "status": "in_progress",
          "phone_verified_at": null,
          "sms_phone_number": null,
          "global_phone_number": "+13151515151",
          "sms_notification": true,
          "current_stage": "Application",
          "position": {
              "digest_key": "f353eca6",
              "title": "Sample position 1"
          },
          "location": {
              "digest_key": "eca510e7",
              "name": "Apple Park 15"
          }
      },
      {
          "digest_key": "98affff2",
          "referer_source": "Jooble",
          "email": "joblexxx@gmail.com",
          "phone": "4321012346",
          "first_name": "Ray",
          "last_name": "Tate",
          "name": "Ray Tate",
          "status": "hired",
          "phone_verified_at": null,
          "sms_phone_number": "+14155693009",
          "global_phone_number": "+15151515151",
          "sms_notification": true,
          "current_stage": "Application",
          "position": {
              "digest_key": "f353eca6",
              "title": "Sample position 1"
          },
          "location": {
              "digest_key": "eca510e7",
              "name": "Apple Park 15"
          }
      }
  ],
  "count": 2
}

Get the applicant by digest_key

HTTP Request

GET /position_applications/:digest_key

HTTP Parameters

param	type	default	required	descrpition
access_token	Bearer Token		yes	HTTP header Authorization Bearer token

Response

JSON format PositionApplication object

{
  "position_application": {
        "digest_key": "98affff2",
        "referer_source": "Jooble",
        "email": "joblexxx@gmail.com",
        "phone": "4321012346",
        "first_name": "Ray",
        "last_name": "Tate",
        "name": "Ray Tate",
        "status": "hired",
        "phone_verified_at": null,
        "sms_phone_number": "+14155693009",
        "global_phone_number": "+15151515151",
        "sms_notification": true,
        "current_stage": "Application",
        "position": {
            "digest_key": "f353eca6",
            "title": "Sample position 1"
        },
        "location": {
            "digest_key": "eca510e7",
            "name": "Apple Park 15"
        }
    }
}

Employee

Get all employees

HTTP Request

GET /employees

HTTP Parameters

param	type	required	description
access_token	Bearer Token	yes	HTTP header Authorization Bearer token
first_name	string	no	filter applicants by first name
last_name	string	no	filter applicants by last name
begin_start_date	string	no	filter employees after given start date. For example `2020-01-30`
end_start_date	string	no	filter employees before given start date. For example `2020-12-30`
begin_hire_date	string	no	filter employees after given hire date. For example `2020-01-30`
end_hire_date	string	no	filter employees before given hire date. For example `2020-12-30`
begin_apply_date	string	no	filter employees after given apply date. For example `2020-01-30`
end_apply_date	string	no	filter employees before given start date. For example `2020-12-30`
begin_onboard_date	string	no	filter employees after given onboard timestamp. For example `2020-12-30T00:00:00.000Z`
end_onboard_date	string	no	filter employees before given onboard timestamp. For example `2020-12-30T00:00:00.000Z`
onboarding_status	string	no	filtler employees by their onboarding status, includes `in_progress`, `completed`and `suspended`

Response

JSON format array of employees

Response Schema

attribute	type	description
employee_id	uuid	The unique identifier associated with this employee
first_name	string	The employee’s first name
middle_initial	string	The employee’s middle initial
last_name	string	The employee’s last name
applied_date	date	The date on which employee applied for the job
hired_date	date	The employee’s hired date
start_date	date	The employee’s start date
onboard_date	datetime	The timestamp on which employee completed onboarding
onboarding_status	string	The employee onboarding process status

[
    {
    "employee_id": "d404e957-af95-4776-af16-bae088e49165",
    "first_name": "Marcos",
    "middle_initial":"D",
    "last_name": "Stevens",
    "applied_date": "2022-06-05",
    "hired_date": "2022-06-05",
    "start_date": "2022-06-06",
    "onboard_date": "2022-05-24T00:10:13.106Z",
    "onboarding_status": "completed"
    },
    {
    "employee_id": "01bc142c-ec76-4cc1-a4a6-419689b32007", 
    "first_name": "XiaoLong", 
    "middle_initial": "D", 
    "last_name": "Li",
    "applied_date": "2022-07-03",
    "hired_date": "2022-07-05",
    "start_date": "2022-08-01",
    "onboard_date": null,
    "onboarding_status": "in_progress"
    }
]

Get the employee

HTTP Request

GET /employees/{employee_id}

HTTP Parameters

param	type	default	required	descrpition
access_token	Bearer Token		yes	HTTP header Authorization Bearer token
employee_id	uuid		yes	Employee Id

Response

JSON format employee’s detail information for a specific employee

Response Schema

Employee object

attribute	type	description
employee_id	uuid	The unique identifier associated with this employee
first_name	string	The employee’s first name
last_name	string	The employee’s last name
middle_initial	string	The employee’s middle initial
phone	string	The employee’s phone number
email	string	The employee’s email address
birthday	date	Information about the employee’s date of birth
ethnicity	string	The employee’s ethnicity, enum: `white` `black_or_african_american` `hispanic_or_latino` `american_indian_or_alaskan_native` `asian` `native_hawaiian_or_other_pacific_islander` `two_or_more_races` `not_specified`
gender	string	The employee’s gender, enum: `female` `male` `non_binary`
ssn	string	The employee’s social security number
marital_status	string	Information about the employee’s marital status, enum: `never_married` `married` `separated` `divorced` `widowed`
address	address object	The employee’s home address
emergency_contact	emergency contact object	Details about the employee’s emergency contact information
employment_details	employment details object	The employee’s employment details
work_location	work location object	The employee’s working location
compensation	compensation object	Information about the employee’s compensation

address object

attribute	type	description
address	string	The street address information
city	string	The city information
country	string	The country information
state	string	The state information
zipcode	string	The zipcode information

emergency contact object

attribute	type	description
name	string	The emergency contact’s name
email	string	The emergency contact’s email address
phone	string	The emergency contact’s phone number
relationship	string	The relationship of emergency contact

employment details object

attribute	type	description
applied_date	date	The date on which employee applied for the job
department_name	string	The employee’s department
hired_date	date	The employee’s hired date
job_title	string	The employee’s job title
manager	string	The employee’s manager
start_date	date	The employee’s start date

work location object

attribute	type	description
address	string	The work location’s street address
city	string	The work location’s city
country	string	The work location’s country
name	string	The work location name
state	string	The work location’s state
zipcode	string	The work location’s zipcode

compensation object

attribute	type	description
additional_remuneration	string	The additional remuneration amount
additional_remuneration_currency_code	string	The additional remuneration currency code, enum: `USD` `SGD`
employment_status	string	The employment status, enum: `full_time` `part_time` `contract` `internship` `temporary` `commission`
status	string	The compensation status, enum: `exempt` `non-exempt`
wage_amount	string	The wage amount
wage_currency_code	string	The wage currency code, enum: `USD` `SGD`
wage_pay_frequency	string	The wage pay frequency, enum: `hour` `day` `week` `month` `year`

{
    "employee_id": "4e98c62e-6f37-4957-bab5-00121f475682",
    "first_name": "Ryan",
    "middle_initial": "J",
    "last_name": "Folk",
    "phone": "+17789882873",
    "email": "wadam@example.fr",
    "birthday": "2005-02-07",
    "ethnicity": "black_or_african_american",
    "gender": "male",
    "ssn": "0015594",
    "marital_status": "never_married",
    "address": {
        "address": "6488 Gateway dr",
        "city": "Washington",
        "country": "United States",
        "state": "Virginia",
        "zipcode": "23703"
    },
    "emergency_contact": {
        "name": "Melinda Folk",
        "email": "folk@example.fr",
        "phone": "+16084559135",
        "relationship": "Father"
    },
    "employment_details": {
        "applied_date": "2022-06-05",
        "department_name": "Staff",
        "hired_date": "2022-06-05",
        "job_title": "Barista",
        "manager": "Test Manager",
        "start_date": "2022-06-06"
    },
    "work_location": {
        "address": "800 King's Way",
        "city": "Vancouver",
        "country": "US",
        "name": "Store",
        "state": "VA",
        "zipcode": "23321"
    },
    "compensation": {
        "additional_remuneration": "2",
        "additional_remuneration_currency_code": "USD",
        "employment_status": "part_time",
        "status": "non-exempt",
        "wage_amount": "12",
        "wage_currency_code": "USD",
        "wage_pay_frequency": "hour"
    }
}

Get the employee’s direct deposits

HTTP Request

GET /employees/{employee_id}/direct_deposits

HTTP Parameters

param	type	default	required	descrpition
access_token	Bearer Token		yes	HTTP header Authorization Bearer token
employee_id	uuid		yes	Employee Id

Response

JSON format employee’s direct deposits for a specific employee

Response Schema

attribute	type	default	description
account_number	string		The bank account number
account_type	string		The bank account type
percentage	integer		Percentage of compensation credited into this account
routing_number	string		The bank rounting number
status	string	`active`	Information about the bank account’s status, enum: `active` `inactive`

[
  {
    "account_number": "112223344",
    "account_type": "saving",
    "percentage": 100,
    "routing_number": "00356",
    "status": "active"
  },
  {
    "account_number": "11334422",
    "account_type": "checking",
    "percentage": 0,
    "routing_number": "00356",
    "status": "inactive"
  }
]

Get the employee’s federal tax info

HTTP Request

GET /employees/{employee_id}/federal_tax_info

HTTP Parameters

param	type	default	required	descrpition
access_token	Bearer Token		yes	HTTP header Authorization Bearer token
employee_id	uuid		yes	Employee Id

Response

JSON format employee’s federal tax info for a specific employee

Response Schema

attribute	type	description
deductions	integer	Information about tax deductions amount
extra_withholding	integer	Information about extra withholding amount
filing_status	string	Information about filing status
other_income	integer	Information about other income amount
qualifying_children_num	integer	Information about qualifying children amount
qualifying_other_num	integer	Information about qualifying other amount
two_jobs	boolean	Whether the employee has two jobs or not

{
  "deductions": 1,
  "extra_withholding": 1,
  "filing_status": "MyString",
  "other_income": 1,
  "qualifying_children_num": 1,
  "qualifying_other_num": 1,
  "two_jobs": false
 }

Get the employee’s state tax info

HTTP Request

GET /employees/{employee_id}/state_tax_info

HTTP Parameters

param	type	default	required	descrpition
access_token	Bearer Token		yes	HTTP header Authorization Bearer token
employee_id	uuid		yes	Employee Id

Response

JSON format employee’s state tax info for a specific employee

Response Schema

attribute	type	description
allowances_exemptions	integer	Information about allowed exemptions amount
extra_withholding	integer	Information about extra withholding amount
filing_status	string	Information about filing status, enum: `single_or_married_filing_separately` `married_jointly_or_qualifying_widower` `head_of_household`
tax_form	string	Tax form details

{
  "allowances_exemptions": 1,
  "extra_withholding": 1,
  "filing_status": "head_of_household",
  "tax_form": "MyString"
 }

Get the employee’s eligibility info

HTTP Request

GET /employees/{employee_id}/eligibility

HTTP Parameters

param	type	default	required	descrpition
access_token	Bearer Token		yes	HTTP header Authorization Bearer token
employee_id	uuid		yes	Employee Id

Response

JSON format employee’s state tax info for a specific employee

Response Schema

attribute	type	description
admission_number	string	The employee’s I-94 admission number, if applicable
alien_authorized_to_work_expiration_date	date	Employee’s alien authorized to work expiration date, if applicable
alien_registration_or_uscis_number	string	Employee’s alien registration or uscis number
country_of_issuance	string	Country of issuance of employee’s passport
lawful_permanent_resident_alien_registration_or_uscis_number	integer	Employee’s lawful permanent resident alien registration or uscis number
passport_number	string	Employee’s passport number
resident_status_code	string	Employee’s resident status code
social_security_number	integer	Employee’s social security number, if applicable

{
  "admission_number": "1",
  "alien_authorized_to_work_expiration_date": "2021-12-20",
  "alien_registration_or_uscis_number": "E123456",
  "country_of_issuance": "USA",
  "lawful_permanent_resident_alien_registration_or_uscis_number": "P123456",
  "passport_number": "E123456",
    "resident_status_code": "PR",
    "social_security_number": 123456
 }

Errors

Normal API response HTTP Status Code is 2xx or 3xx. If encounter error，HTTP Status Code is 4xx or 5xx, and response body includes error message.

Introduction

Concepts

Position

Position object attributes

Position Application

Position Application object attributes

Authorization

Create access token

HTTP Parameters

Response

Revoke access token

HTTP Parameters

Response

Position

Position object

Get All positions

HTTP Request

HTTP Parameters

Response

Get the position by digest_key

HTTP Request

HTTP Parameters

Response

Applicant

PositionApplication object

Get All applicants

HTTP Request

HTTP Parameters

Response

Get the applicant by digest_key

HTTP Request

HTTP Parameters

Response

Employee

Get all employees

HTTP Request

HTTP Parameters

Response

Response Schema

Get the employee

HTTP Request

HTTP Parameters

Response

Response Schema

Employee object

address object

emergency contact object

employment details object

work location object

compensation object

Get the employee’s direct deposits

HTTP Request

HTTP Parameters

Response

Response Schema

Get the employee’s federal tax info

HTTP Request

HTTP Parameters

Response

Response Schema

Get the employee’s state tax info

HTTP Request

HTTP Parameters

Response

Response Schema

Get the employee’s eligibility info

HTTP Request

HTTP Parameters

Response

Response Schema

Errors

Changelog

API changelog

API documentation Changelog