Workstream Team Members API

openapi: 3.0.2
info:
  version: 1.0.0
  title: Workstream Public Applicants Team Members API
  termsOfService: https://workstream.us/terms/
  contact:
    email: help@workstream.is
    url: https://help.workstream.us/en/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: workstream-logo.svg
    href: '#'
  description: '# API Reference


    The Workstream API is a modern, [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Our API has predictable resource-oriented URLs, supports HTTPS authentication, verbs and response codes, and returns JSON-encoded responses.


    **Note:** [Old APIs](https://old-api-doc.workstream.us/) will be deprecated, please refer to this API documentation for new API usages.

    '
servers:
- url: https://{tenant}
  variables:
    tenant:
      default: public-api.workstream.us
      description: Public API URI
tags:
- name: Team Members
  description: Team Members represent team members that are managed within your company.
paths:
  /team_members/{uuid}:
    get:
      operationId: GetTeamMember
      tags:
      - Team Members
      summary: Retrieve an existing Team Member
      description: Retrieves an existing Team Member.
      security:
      - bearerAuth: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: embed
        in: query
        schema:
          type: string
          example: (location, job_title, department, information, state_tax, federal_tax, eligibility, direct_deposits)
        description: Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              schema:
                type: string
              description: A randomly generated request-id to uniquely identify each request sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/team_member'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
  /team_members/{uuid}/status:
    put:
      operationId: UpdateTeamMemberStatus
      tags:
      - Team Members
      summary: Update an existing Team Member's status
      description: Updates an existing Team Member's status.
      security:
      - bearerAuth: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - hired
                  - active
                  - offboarded
                last_day_of_work:
                  type: string
                  description: The last day of work. **Required** when updating a team member's status to `offboarded`.
                  format: date
                note:
                  type: string
                  description: The offboard note. **Optional** when updating a team member's status to `offboarded`.
                rehireable:
                  type: boolean
                  description: Whether the team member can be rehired. **Optional** when setting a team member's status to `offboarded`.
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              schema:
                type: string
              description: A randomly generated request-id to uniquely identify each request sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/base'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
  /team_members:
    get:
      operationId: GetTeamMembers
      summary: List existing Team Members
      description: Lists existing Team Members with the input parameters.
      tags:
      - Team Members
      security:
      - bearerAuth: []
      parameters:
      - name: first_name
        in: query
        schema:
          type: string
          example: Andy
        description: Returns team members with the input `first_name`.
      - name: last_name
        in: query
        schema:
          type: string
          example: Lee
        description: Returns team members with the input `last_name`.
      - name: status
        in: query
        schema:
          type: string
          enum:
          - hired
          - active
          - offboarded
        description: Returns team members with the input status.
      - name: location[uuid]
        in: query
        schema:
          type: string
          format: uuid
          example: c59c9852-2584-11ee-be56-0242ac120002
        description: Returns team members with the input location's UUID.
      - name: job_title[title]
        in: query
        schema:
          type: string
          example: Bus Driver
        description: Returns team members with the input job_title's title.
      - name: start_date.gte
        in: query
        schema:
          type: string
          format: date
          example: '2022-09-30'
        description: Returns team members with `start_date` after or equals to the input date.
      - name: start_date.lte
        in: query
        schema:
          type: string
          format: date
          example: '2022-09-30'
        description: Returns team members with `start_date` before or equals to the input date.
      - name: embed
        in: query
        schema:
          type: string
          example: (location, job_title, department, information, state_tax, federal_tax, eligibility, direct_deposits)
        description: Specifies the names of resources that should be embedded in the response. Resources to embed must have parentheses and be comma-separated.
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              schema:
                type: string
              description: A randomly generated request_id to uniquely identify each request sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/team_member'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
    post:
      operationId: CreateTeamMember
      summary: Create a new Team Member resource
      description: Creates a new Team Member resource.
      tags:
      - Team Members
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                team_member:
                  $ref: '#/components/schemas/creation-2'
      responses:
        '201':
          description: Returns the newly created Team Member.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: A randomly generated request_id to uniquely identify each request sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    format: uuid
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
components:
  schemas:
    state_tax-2:
      type: object
      title: State Tax
      description: Need to embed **state_tax** in request query params.
      properties:
        allowances_exemptions:
          description: allowed exemptions amount
          type: integer
        extra_withholding:
          description: extra withholding amount
          type: integer
        filing_status:
          description: filing status
          type: string
        tax_form:
          description: tax form name
          type: string
    custom_field:
      type: array
      title: custom field
      description: Need to embed **custom_fields** in request query params.
      items:
        type: object
        properties:
          uuid:
            description: Custom field uuid
            type: string
            example: 509a251a-93af-41e3-8416-23b29dc293cc
          title:
            description: Custom field title
            type: string
            example: custom field title
          value:
            description: Custom field value
            type: string
            example: custom field value
    federal_tax-2:
      type: object
      title: Federal Tax
      description: Need to embed **federal_tax** in request query params.
      properties:
        deductions:
          description: tax deductions amount
          type: integer
        extra_withholding:
          description: extra withholding amount
          type: integer
        filing_status:
          description: filing status
          type: string
        other_income:
          description: other income amount
          type: integer
        qualifying_children_num:
          description: qualifying children amount
          type: integer
        qualifying_other_num:
          description: qualifying other amount
          type: integer
        two_jobs:
          description: whether the employee has two jobs or not
          type: boolean
    base:
      type: object
      title: Team Member
      properties:
        uuid:
          type: string
          format: uuid
        first_name:
          description: Team member's first name.
          type: string
          example: Ryan
        middle_initial:
          description: Team member's middle initial.
          type: string
          example: J
        last_name:
          description: Team member's last name.
          type: string
          example: Folk
        preferred_name:
          description: Team member's preferred name. Returned as `null` for team members who have not set one.
          type: string
          nullable: true
          example: Johnny
        termination_note:
          description: Team member's termination note.
          type: string
          format: nullable
        start_date:
          description: Team member's start date.
          type: string
          format: date
        status:
          description: Status of the team member.
          type: string
          enum:
          - hired
          - active
          - offboarded
    creation-2:
      required:
      - first_name
      - last_name
      - dob
      - phone
      - status
      - start_date
      - location
      - job_title
      - department
      - government_ids
      type: object
      title: Team Member Creation Payload
      properties:
        first_name:
          type: string
          description: Team member's first name.
          example: Ryan
        middle_initial:
          type: string
          description: Team member's middle initial.
          example: J
        last_name:
          type: string
          description: Team member's last name.
          example: Folk
        preferred_name:
          type: string
          description: Team member's preferred name (optional).
          example: Johnny
        dob:
          type: string
          description: Team member's date of birth.
          format: date
          example: '2020-04-01'
        phone:
          type: string
          description: Team member's phone number.
          example: '+17789882873'
        email:
          type: string
          description: Team member's email address.
          example: wadam@example.fr
        gender:
          type: string
          description: Team member's gender.
          enum:
          - female
          - male
          - non_binary
          example: male
        status:
          type: string
          description: Status of the team member.
          enum:
          - hired
          - active
          - offboarded
        start_date:
          type: string
          description: Team member's employment start date.
          format: date
          example: '2023-05-01'
        location:
          type: object
          description: Team member's work location.
          properties:
            uuid:
              type: string
              format: uuid
              description: Team member's work location ID.
        job_title:
          type: object
          description: Team member's job title.
          properties:
            uuid:
              type: string
              format: uuid
              description: Team member's job title ID.
        department:
          type: object
          description: Team member's department.
          properties:
            uuid:
              type: string
              format: uuid
              description: Team member's department ID.
        government_ids:
          type: array
          description: Array of team member's government IDs. Only Social Security Number is accepted at the moment.
          items:
            type: object
            description: government ID
            properties:
              type:
                type: string
                enum:
                - SSN
              value:
                type: string
                example: '222521248'
        metadata:
          type: object
          description: Customer-defined key-value pairs. Use this parameter to store additional information on your candidate.
    location-3:
      type: object
      title: Location
      description: Need to embed **location** in request query params
      properties:
        uuid:
          type: string
          format: uuid
          example: c59c9852-2584-11ee-be56-0242ac120002
        name:
          type: string
          example: SF store
    state_tax:
      type: object
      title: employee's state tax info
      description: Need to embed **state_tax** in request query params.
      properties:
        allowances_exemptions:
          description: allowed exemptions amount
          type: integer
        extra_withholding:
          description: extra withholding amount
          type: integer
        filing_status:
          description: filing status
          type: string
        tax_form:
          description: tax form name
          type: string
        state:
          description: tax form state
          type: string
        tax_form_details:
          description: tax form details
          type: object
    job_title:
      type: object
      title: Job Title
      description: Need to embed **job_title** in request query params
      properties:
        uuid:
          type: string
          format: uuid
          example: c59c9852-2584-11ee-be56-0242ac120002
        title:
          type: string
          example: Bus Driver
    information-2:
      type: object
      title: Information
      description: Need to embed **information** in request query params.
      properties:
        phone:
          description: Team member's phone number.
          type: string
          example: '+17789882873'
        email:
          description: Team member's email address.
          type: string
          example: wadam@example.fr
        dob:
          description: Team member's date of birth.
          type: string
          format: date
          example: '2020-04-01'
        ethnicity:
          description: Team member's ethnicity.
          type: string
          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
          example: black_or_african_american
        gender:
          description: Team member's gender.
          type: string
          enum:
          - female
          - male
          - non_binary
          example: male
        ssn:
          description: Team member's social security number.
          type: string
          example: '222521248'
        marital_status:
          description: Team member's marital status.
          type: string
          enum:
          - never_married
          - married
          - separated
          - divorced
          - widowed
          example: never_married
    department-3:
      type: object
      title: Department
      description: Need to embed **department** in request query params
      properties:
        uuid:
          type: string
          format: uuid
          example: c59c9852-2584-11ee-be56-0242ac120002
        name:
          type: string
          example: Marketing
    direct_deposit:
      type: object
      title: employee's direct_deposit
      properties:
        account_number:
          description: bank account number
          type: string
          example: '112223344'
        account_type:
          description: bank account type
          type: string
          example: saving
        percentage:
          description: percentage of compensation credited into this account
          type: integer
        routing_number:
          description: bank rounting number
          type: string
          example: '00356'
        status:
          description: bank account status
          type: string
          enum:
          - active
          - inactive
    team_member:
      allOf:
      - $ref: '#/components/schemas/base'
      - type: object
        properties:
          job_title:
            $ref: '#/components/schemas/job_title'
          location:
            $ref: '#/components/schemas/location-3'
          department:
            $ref: '#/components/schemas/department-3'
          information:
            $ref: '#/components/schemas/information-2'
          direct_deposits:
            type: array
            description: Need to embed **direct_deposits** in request query params.
            items:
              $ref: '#/components/schemas/direct_deposit'
          state_tax:
            $ref: '#/components/schemas/state_tax'
          federal_tax:
            $ref: '#/components/schemas/federal_tax-2'
          eligibility:
            $ref: '#/components/schemas/state_tax-2'
          custom_fields:
            $ref: '#/components/schemas/custom_field'
  responses:
    '422':
      description: Unprocessable Entity - Invalid query params or request body.
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              error_code:
                type: integer
                example: 13422
              message:
                type: string
                example: (forbidden_embedded_resources}) is not a supported 'embed'. Valid 'embed' keys are (permitted_embedded_resources).
    '403':
      description: Forbidden - The user is not authorized to use this resource.
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              error_code:
                type: integer
                example: 13403
              message:
                type: string
                example: Forbidden - The user is not authorized to use this resource.
    '401':
      description: Unauthorized - Credentials are not valid for the target resource.
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              error_code:
                type: integer
                example: 13401
              message:
                type: string
                example: Unauthorized
    '404':
      description: Not found - The requested resource is not found.
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              error_code:
                type: integer
                example: 13404
              message:
                type: string
                example: The requested resource is not found.
    '429':
      description: Too many requests.
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              error_code:
                type: integer
                example: 13429
              message:
                type: string
                example: Throttle limit reached. Limit to 100 requests in 60 seconds.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://public-api.workstream.us/
          scopes:
            Applicants: Read Applicant records
            Employees: Read Employee records
            Company Users: Read Company User records
            Company Roles: Read Company Role records
            Positions: Read Position records
            TeamMember: Read Team Member records
            Locations: Read Location records
            Departments: Read Department records
            Imported Employee Infos: Read Imported Employee Info records
            Custom Field: Read, update custom field and custom field values
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT