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.

        '