Workstream Positions API
Positions represent open job requisitions within your company that are looking to be filled.
OpenAPI Specification
openapi: 3.0.2
info:
version: 1.0.0
title: Workstream Public Applicants Positions 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: Positions
description: Positions represent open job requisitions within your company that are looking to be filled.
paths:
/positions/{uuid}:
get:
operationId: GetPosition
tags:
- Positions
summary: Retrieve an existing Position
description: Retrieves an existing Position.
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: embed
in: query
schema:
type: string
example: (location, custom_fields)
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/position'
'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'
/positions:
get:
operationId: GetPositions
tags:
- Positions
summary: List existing Positions
description: Lists existing Positions with the input parameters.
security:
- bearerAuth: []
parameters:
- name: title
in: query
schema:
type: string
example: Cook
description: Returns positions with the input `title`.
- name: status
in: query
schema:
type: string
enum:
- pending
- published
- closed
- deleted
example: published
description: Returns positions with the input `status`.
- name: access
in: query
schema:
type: string
enum:
- link_only
- public
example: link_only
description: Returns positions with input `access`.
- name: location[name]
in: query
schema:
type: string
example: SF%20Store
description: Returns positions with the input location's name.
- name: created_at.gte
in: query
schema:
type: string
format: timestamp
example: '2022-09-30 00:00:00.000Z'
description: Returns positions created after or equals to the input date.
- name: created_at.lte
in: query
schema:
type: string
example: '2022-09-30 00:00:00.000Z'
description: Returns positions created before or equals to the input date.
- name: embed
in: query
schema:
type: string
example: (location, custom_fields)
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/position'
'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:
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
location:
type: object
title: Position's location
description: Need to embed **location** in request query params.
properties:
uuid:
description: Location uuid
type: string
example: fc4487ce-67n0-436e-9aa7-a2eb496aff0e
name:
description: location name
type: string
example: SF store
address:
description: location's street address
type: string
postal_code:
description: location's postal code
type: string
city:
description: location's city
type: string
state:
description: location's state
type: string
country:
description: location's country
type: string
position:
type: object
title: Position
properties:
uuid:
description: Position uuid
type: string
format: uuid
example: c59c9852-2584-11ee-be56-0242ac120002
digest_key:
description: Position digest_key
type: string
example: 40ad0bd6836b9e5cfedbf28e7c907fe229a99a2a
title:
description: Position title
type: string
example: Customer Success Associate
overview:
description: Position title
type: string
example: We are looking for a full-time, dedicated, and passionate individual to join our growing team.
status:
description: Position title
type: string
enum:
- published
- pending
- closed
- deleted
example: published
number:
description: Position number
type: string
example: '1845'
access:
description: Position access
type: string
example: public
pay_amount:
description: Position pay_amount
type: string
example: 15$
pay_frequency:
description: Position pay_frequency
type: string
example: hourly
job_type:
description: Position job_type
type: string
example: full_time
normalized_titles:
description: Position normalized_titles
type: string
remote_type:
description: Position remote_type
type: string
example: on_site
job_url:
description: Position job_url
type: string
example: https://got.work/ryan_burgers_ryans_radical_rapping_teddy_bears/ad4b4e75
location:
$ref: '#/components/schemas/location'
custom_fields:
$ref: '#/components/schemas/custom_field'
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