Ashby Job API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Job API
  description: Complete public API for accessing resources in your Ashby instance. Includes applications, candidates, jobs, interviews, offers, surveys, custom fields, organization metadata, files, reports, approvals, and webhooks.
  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`](https://developers.ashbyhq.com/reference/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`](https://developers.ashbyhq.com/reference/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: HTTP Basic Auth. Send your Ashby API key as the username and leave the password blank.
    WebhookSignature:
      type: apiKey
      in: header
      name: Ashby-Signature
      description: HMAC-SHA256 signature of the webhook payload, used to verify webhook authenticity.