openapi: 3.1.0
info:
version: 1.0.0
title: Ashby API Key Job API
description: The public API for accessing resources in your Ashby instance.
contact:
name: Ashby Support
url: https://app.ashbyhq.com/support
email: support@ashbyhq.com
servers:
- url: https://api.ashbyhq.com
security:
- BasicAuth: []
tags:
- name: Job
paths:
/job.create:
post:
summary: job.create
operationId: jobCreate
description: 'Creates a new job
**Requires the [`jobsWrite`](authentication#permissions-jobcreate) permission.**
To set values for custom fields on Jobs, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
'
tags:
- Job
requestBody:
content:
application/json:
schema:
type: object
properties:
title:
type: string
example: Software Engineer
description: The title of the job.
teamId:
allOf:
- description: The id of the department or team associated with the job
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
locationId:
allOf:
- description: The id of the location of the job
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
defaultInterviewPlanId:
allOf:
- description: "The id of the default interview plan for this job. \nA job cannot be opened without a default interview plan.\n"
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
jobTemplateId:
allOf:
- description: 'The id of the job template to use for this job.
Only active job templates can be used to create a job.
'
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
brandId:
allOf:
- description: The id of the brand to use for this job
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
required:
- title
- teamId
- locationId
responses:
'200':
description: Responses for the job.create endpoint
content:
application/json:
schema:
oneOf:
- title: Success response
allOf:
- $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
- type: object
properties:
results:
$ref: '#/webhooks/jobCreate/post/requestBody/content/application~1json/schema/properties/data/properties/job'
required:
- results
- $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
/job.info:
post:
summary: job.info
operationId: jobInfo
description: 'Returns details about a single job by id
**Requires the [`jobsRead`](authentication#permissions-jobinfo) permission.**
'
tags:
- Job
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
allOf:
- description: The id of the job to fetch
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
includeUnpublishedJobPostingsIds:
type: boolean
description: Include unpublished job posting ids
expand:
type: array
description: "Choose to expand the result and include additional data for related objects. \n"
items:
type: string
enum:
- location
- openings
required:
- id
responses:
'200':
description: Responses for the job.info endpoint
content:
application/json:
schema:
oneOf:
- title: Success response
allOf:
- type: object
required:
- success
properties:
success:
type: boolean
description: Whether the response is considered successful.
- type: object
properties:
results:
allOf:
- $ref: '#/webhooks/jobCreate/post/requestBody/content/application~1json/schema/properties/data/properties/job'
- type: object
properties:
location:
allOf:
- $ref: '#/paths/~1location.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
- description: The location will only be included if the `location` expand parameter is included when the request is made.
openings:
description: The openings array will only be included if the `openings` expand parameter is included when the request is made.
type: array
items:
$ref: '#/webhooks/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
compensation:
description: The compensation object will only be included if the `compensation` expand parameter is included when the request is made.
type: object
properties:
compensationTiers:
$ref: '#/paths/~1job.updateCompensation/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/allOf/0/properties/compensationTiers'
description: The compensation ranges that can be offered to applicants for this posting
required:
- results
- $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
/job.list:
post:
summary: job.list
description: 'List all open, closed, and archived jobs.
See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.
**Requires the [`jobsRead`](authentication#permissions-joblist) permission.**
To include draft jobs, `Draft` must be specified in the `status` param.
'
operationId: jobList
tags:
- Job
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1opening.list/post/requestBody/content/application~1json/schema'
- type: object
properties:
status:
type: array
description: When supplied, only jobs with the provided status(es) will be returned.
items:
$ref: '#/paths/~1job.setStatus/post/requestBody/content/application~1json/schema/properties/status/allOf/1'
openedAfter:
type: integer
format: int64
description: Return jobs opened after this date, which is the time since the unix epoch in milliseconds
openedBefore:
type: integer
format: int64
description: Return jobs opened before this date, which is the time since the unix epoch in milliseconds
closedAfter:
type: integer
format: int64
description: Return jobs closed after this date, which is the time since the unix epoch in milliseconds
closedBefore:
type: integer
format: int64
description: Return jobs closed before this date, which is the time since the unix epoch in milliseconds
includeUnpublishedJobPostingsIds:
type: boolean
description: Include unpublished job posting ids
expand:
$ref: '#/paths/~1job.info/post/requestBody/content/application~1json/schema/properties/expand'
responses:
'200':
description: Responses for the jobPosting.list endpoint
content:
application/json:
schema:
oneOf:
- title: Success response
allOf:
- allOf:
- $ref: '#/paths/~1brand.list/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
- type: object
properties:
syncToken:
$ref: '#/paths/~1opening.list/post/requestBody/content/application~1json/schema/properties/syncToken'
- type: object
properties:
results:
type: array
items:
allOf:
- $ref: '#/webhooks/jobCreate/post/requestBody/content/application~1json/schema/properties/data/properties/job'
- $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/allOf/1'
required:
- results
- title: Error response
$ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
/job.setStatus:
post:
summary: job.setStatus
operationId: jobSetStatus
description: "Sets the status on a job by id.\n\n**Requires the [`jobsWrite`](authentication#permissions-jobsetstatus) permission.**\n\nAll jobs are drafts when they're first created. There are a few validations around the stages a job can be transitioned to:\n- Drafts can be changed to Open or Archived\n- Open jobs can be changed to Closed\n- Closed jobs can be changed to Draft or Archived\n- Archived jobs can be changed to a Draft \n"
tags:
- Job
requestBody:
content:
application/json:
schema:
type: object
properties:
jobId:
allOf:
- description: The unique id of the job to set the status of.
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
status:
allOf:
- description: The status to apply to the job.
- type: string
enum:
- Draft
- Open
- Closed
- Archived
required:
- jobId
- status
responses:
'200':
description: Responses for the job.setStatus endpoint
content:
application/json:
schema:
oneOf:
- title: Success response
allOf:
- $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
- type: object
properties:
results:
$ref: '#/webhooks/jobCreate/post/requestBody/content/application~1json/schema/properties/data/properties/job'
required:
- results
- $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
/job.update:
post:
summary: job.update
operationId: jobUpdate
description: 'Updates an existing job
**Requires the [`jobsWrite`](authentication#permissions-jobupdate) permission.**
To set values for custom fields on Jobs, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
'
tags:
- Job
requestBody:
content:
application/json:
schema:
type: object
properties:
jobId:
allOf:
- description: The unique id of the job to update.
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
title:
type: string
example: Software Engineer
description: A new title for the job.
teamId:
allOf:
- description: The new team to associate with the job.
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
locationId:
allOf:
- description: The new location to associate with the job.
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
defaultInterviewPlanId:
allOf:
- description: The new default interview plan to associate with the job.
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
customRequisitionId:
allOf:
- description: The new default custom requisition id for the job.
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
required:
- jobId
responses:
'200':
description: Responses for the job.update endpoint
content:
application/json:
schema:
oneOf:
- title: Success response
allOf:
- $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
- type: object
properties:
results:
$ref: '#/webhooks/jobCreate/post/requestBody/content/application~1json/schema/properties/data/properties/job'
required:
- results
- $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
/job.updateCompensation:
post:
summary: job.updateCompensation
operationId: jobUpdateCompensation
description: 'Updates an existing job''s compensation tiers
**Requires the [`jobsWrite`](authentication#permissions-jobupdate) permission.**
'
tags:
- Job
requestBody:
content:
application/json:
schema:
type: object
properties:
jobId:
allOf:
- description: The unique id of the job to update.
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
compensationTiers:
type: array
items:
type: object
description: A valid compensation range that can be offered to candidates
properties:
title:
type: string
example: Zone A
description: A label that describes the entire range to applicants. Title is required for multi-tier compensation ranges.
additionalInformation:
type: string
example: Signing bonus available
description: Supplementary information about the compensation
components:
type: array
description: The individual components that make up this compensation range
items:
allOf:
- type: object
properties:
compensationType:
type: string
enum:
- Salary
- EquityPercentage
- EquityCashValue
- Commission
- Bonus
example: Salary
description: 'The type of compensation this component represents
'
interval:
type: string
enum:
- NONE
- 1 TIME
- 1 HOUR
- 1 DAY
- 1 WEEK
- 2 WEEK
- 1 MONTH
- 2 MONTH
- 1 YEAR
- 6 MONTH
- 0.5 MONTH
- 3 MONTH
example: 1 YEAR
description: The frequency at which this compensation is given
currencyCode:
type: string
example: EUR
description: 'For non `EquityPercentage` components, the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
currency code of the compensation range
'
label:
type: string
example: Estimated Salary
description: An optional label that describes this compensation range to applicants
minValue:
oneOf:
- type: number
- type: 'null'
example: 72000.1
description: The lower end of the compensation range
maxValue:
oneOf:
- type: number
- type: 'null'
example: 100000
description: The higher end of the compensation range
required:
- compensationType
- interval
- type: object
required:
- minValue
- maxValue
example:
- compensationType: Salary
interval: 1 YEAR
currencyCode: EUR
minValue: 72023.45
maxValue: 100000
- compensationType: EquityPercentage
interval: NONE
minValue: 1
maxValue: 2.511
- compensationType: Bonus
interval: 1 YEAR
minValue: null
maxValue: null
required:
- components
required:
- jobId
- compensationTiers
responses:
'200':
description: Responses for the job.update endpoint
content:
application/json:
schema:
oneOf:
- title: Success response
allOf:
- $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
- type: object
properties:
results:
description: Job with updated compensation tiers
allOf:
- type: object
properties:
compensationTiers:
description: The compensation ranges that can be offered to applicants for this posting
type: array
items:
type: object
description: A compensation range that can be offered to candidates
properties:
id:
allOf:
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
- description: The compensation tier's unique id
title:
type: string
example: Zone A
description: A label that describes the entire range to applicants
additionalInformation:
type: string
example: Signing bonus available
description: Supplementary information about the compensation
components:
type: array
items:
type: object
description: 'A part of a compensation tier that represents one specific type of compensation, e.g. the "Salary"
or the "Bonus."
'
properties:
id:
allOf:
- $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
- description: The component's unique id
allOf:
- $ref: '#/paths/~1jobPosting.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/compensation/properties/summaryComponents/items'
required:
- id
description: The individual components that make up this compensation range
example:
- id: fb8efeaa-bea1-4713-9012-cbd25fc3dc89
summary: €72K – €100K
compensationType: Salary
interval: 1 YEAR
currencyCode: EUR
minValue: 72023.45
maxValue: 100000
- id: 93c62578-ed5d-42dd-8186-64ad5ba5603d
summary: 1% – 2.511%
compensationType: EquityPercentage
interval: NONE
minValue: 1
maxValue: 2.511
- id: fb8efeaa-bea1-4713-9012-cbd25fc3dc90
summary: Offers Bonus
compensationType: Bonus
interval: 1 YEAR
minValue: null
maxValue: null
tierSummary:
type: string
example: €72K – €100K • 1% – 2.511% • Offers Bonus
description: 'A summary of the tiers''s components in the same format shown on Ashby-hosted Job Boards
'
required:
- id
- components
- tierSummary
example:
- id: da53719f-a115-400b-9d30-9b875428f1e7
title: Zone A
components:
- id: fb8efeaa-bea1-4713-9012-cbd25fc3dc89
summary: €72K – €100K
compensationType: Salary
interval: 1 YEAR
currencyCode: EUR
minValue: 72023.45
maxValue: 100000
- id: 93c62578-ed5d-42dd-8186-64ad5ba5603d
summary: 1% – 1.4%
compensationType: EquityPercentage
interval: NONE
minValue: 1
maxValue: 1.4
tierSummary: €72K – €100K • 1% – 1.4%
- id: 81362ab1-739e-44f5-88d9-dbc5c731624c
title: Zone B
additionalInformation: Commuter Benefits
components:
- id: fb8efeaa-bea1-4713-9012-cbd25fc3dc89
summary: €72K – €100K
compensationType: Salary
interval: 1 YEAR
currencyCode: EUR
minValue: 95010.12
maxValue: 270450
- id: 93c62578-ed5d-42dd-8186-64ad5ba5603d
summary: 1.8% – 2.511%
compensationType: EquityPercentage
interval: NONE
minValue: 1.8
maxValue: 2.511
- id: 5eb15197-8664-48fd-99cf-fbdc9d25149d
summary: Offers Bonus
compensationType: Bonus
interval: 1 YEAR
minValue: null
maxValue: null
tierSummary: €95K – €270K • 1.8% – 2.511% • Offers Bonus • Commuter Benefits
required:
- compensationTiers
- $ref: '#/webhooks/jobCreate/post/requestBody/content/application~1json/schema/properties/data/properties/job'
- required:
- results
- $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
/job.search:
post:
summary: job.search
operationId: jobSearch
description: 'Searches for jobs by title
**Requires the [`jobsRead`](authentication#permissions-jobsearch) permission.**
'
tags:
- Job
requestBody:
content:
application/json:
schema:
type: object
properties:
title:
type: string
example: Software Engineer
description: The title of the job to search for
requisitionId:
type: string
example: REQ-2471
description: The requisition ID of the job to search for
anyOf:
- required:
- title
- required:
- requisitionId
responses:
'200':
description: Responses for the job.search endpoint
content:
application/json:
schema:
oneOf:
- title: Success response
allOf:
- $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
- type: object
properties:
results:
type: array
items:
$ref: '#/webhooks/jobCreate/post/requestBody/content/application~1json/schema/properties/data/properties/job'
required:
- results
- $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: "Use HTTP Basic Auth to authenticate with our API. You must send your API key with every request. \nPut your API key as the basic auth username and leave the password blank.\n"
WebhookSignature:
type: apiKey
in: header
name: Ashby-Signature
description: '[Optional] If you provide a secret token when configuring your webhook, this will be used to create a digest of the JSON payload sent with each webhook request.
The digest will be included in the request under the `Ashby-Signature` http header.
It will look like this:
`Ashby-Signature: sha256=f3124911d2956f10aa3a49c43a88bdf13bba846e94f0ae2bd7c034f90239bd04`
The part before the = indicates the algorithm that was used to compute the hash digest.
'