Workstream Company Roles API

openapi: 3.0.2
info:
  version: 1.0.0
  title: Workstream Public Applicants Company Roles 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: Company Roles
  description: Company Roles represent roles within your company.
paths:
  /company_roles:
    get:
      operationId: GetCompanyRoles
      tags:
      - Company Roles
      summary: List existing Company Roles
      description: Lists existing Company Roles with the input parameters.
      security:
      - bearerAuth: []
      parameters:
      - name: uuid
        in: query
        schema:
          type: string
          format: uuid
          example: 67161b3c-2584-11ee-be56-0242ac120002
        description: Returns the Company Role with the input `UUID`.
      - name: name
        in: query
        schema:
          type: string
          example: Joey
        description: iReturns Company Roles with the input `name`.
      - name: created_at.gte
        in: query
        schema:
          type: string
          format: timestamp
          example: '2020-09-30 00:00:00.000Z'
        description: Returns Company Roles created at or after the input date.
      - name: created_at.lte
        in: query
        schema:
          type: string
          format: timestamp
          example: '2022-09-30 00:00:00.000Z'
        description: Returns Company Roles created at or after the input date.
      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/company_role'
        '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:
  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
    '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.
    '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.
  schemas:
    company_role:
      type: object
      title: Company Role
      properties:
        uuid:
          description: Company Role's unique identifier.
          type: string
          format: uuid
          example: 509a251a-93af-41e3-8416-23b29dc293cc
        name:
          description: Company Role's name.
          type: string
          example: General Manager
        editable:
          description: Whether the Company Role is editable.
          type: boolean
          example: true
        permissions_set:
          description: Company Role's permissions set.
          type: array
          example:
          - edit_user edit_location
          - edit_department
          - customize_notifications
          - edit_position
          - edit_custom_reports
          - edit_custom_field
          - edit_integration
          - edit_company
          items:
            type: string
        created_at:
          description: The date that the Company Role was created.
          type: string
          format: date-time
          example: '2022-09-30T00:00:00.000Z'
  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