openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Openings 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: Openings
paths:
  /opening.info:
    post:
      summary: opening.info
      description: "Retrieves an opening by its UUID.\n      \n**Requires the [`jobsRead`](authentication#permissions-openinginfo) permission.**"
      operationId: openinginfo
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - openingId
              properties:
                openingId:
                  type: string
                  description: The id of the opening
      responses:
        '200':
          description: Responses for the opening.info 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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.list:
    post:
      summary: opening.list
      description: "Lists openings.\n\nSee the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.\n      \n**Requires the [`jobsRead`](authentication#permissions-openinglist) permission.**"
      operationId: openinglist
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                createdAfter:
                  type: integer
                  format: int64
                  description: The API will return data after this date, which is the time since the unix epoch in milliseconds
                cursor:
                  $ref: '#/paths/~1brand.list/post/requestBody/content/application~1json/schema/properties/cursor'
                syncToken:
                  type: string
                  description: 'An opaque token representing the last time the data was successfully synced from the API. A new, updated one is returned after successfully fetching the last page of data.

                    '
                  example: jYnEBmjzR
                limit:
                  $ref: '#/paths/~1brand.list/post/requestBody/content/application~1json/schema/properties/limit'
              example:
                createdAfter: 1659979196538
                cursor: qA
                syncToken: 6W05prn4d
                limit: 25
      responses:
        '200':
          description: Responses for the opening.list 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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.search:
    post:
      summary: opening.search
      description: "Searches for openings by identifier.\n      \n**Requires the [`jobsRead`](authentication#permissions-openingsearch) permission.**"
      operationId: openingsearch
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              properties:
                identifier:
                  type: string
                  description: The identifier of the opening you want to search for
      responses:
        '200':
          description: Responses for the opening.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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.create:
    post:
      summary: opening.create
      description: "Creates an opening.\n      \n**Requires the [`jobsWrite`](authentication#permissions-openingcreate) permission.**\n\nTo set values of custom fields on Openings, use the [`customFields.setValue`](https://developers.ashbyhq.com/reference/customfieldsetvalue) endpoint."
      operationId: openingcreate
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                identifier:
                  type: string
                  description: jobIds,     targetHireDate,     targetStartDate,     isBackfill,     employmentType,
                description:
                  type: string
                teamId:
                  type: string
                  description: The id of the department or team associated with the opening.
                locationIds:
                  type: array
                  description: The ids of the locations associated with the opening.
                  items:
                    type: string
                jobIds:
                  type: array
                  description: The ids of the jobs associated with the opening
                  items:
                    type: string
                targetHireDate:
                  type: string
                  description: The date (in YYYY-MM-DD format) by which you intend to hire against this opening.
                targetStartDate:
                  type: string
                  description: The date (in YYYY-MM-DD format) by which you intend someone hired against this opening will start employment.
                isBackfill:
                  type: boolean
                  description: Whether this opening is intended to backfill a previous employee
                  default: false
                employmentType:
                  type: string
                  description: The employment type for this opening
                  default: FullTime
                  enum:
                  - FullTime
                  - PartTime
                  - Intern
                  - Contract
                  - Temporary
                  - ''
                openingState:
                  type: string
                  description: The state the opening should be created in. Defaults to `Draft`. If not Draft, additional validation will be performed.
                  enum:
                  - Draft
                  - Approved
                  - Open
                  - Closed
      responses:
        '200':
          description: Responses for the opening.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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.addJob:
    post:
      summary: opening.addJob
      description: "Adds a job to an opening.\n      \n**Requires the [`jobsWrite`](authentication#permissions-openingaddjob) permission.**"
      operationId: openingaddjob
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - openingId
              - jobId
              properties:
                openingId:
                  type: string
                  description: The id of the opening
                jobId:
                  type: string
                  description: The id of the job to add
      responses:
        '200':
          description: Responses for the opening.addJob 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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.removeJob:
    post:
      summary: opening.removeJob
      description: "Removes a job from an opening.\n      \n**Requires the [`jobsWrite`](authentication#permissions-openingremovejob) permission.**"
      operationId: openingremovejob
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - openingId
              - jobId
              properties:
                openingId:
                  type: string
                  description: The id of the opening
                jobId:
                  type: string
                  description: The id of the job to remove from the opening.
      responses:
        '200':
          description: Responses for the opening.removeJob 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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.addLocation:
    post:
      summary: opening.addLocation
      description: "Adds a location to an opening.\n      \n**Requires the [`jobsWrite`](authentication#permissions-openingaddlocation) permission.**"
      operationId: openingaddlocation
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - openingId
              - locationId
              properties:
                openingId:
                  type: string
                  description: The id of the opening
                locationId:
                  type: string
                  description: The id of the location to add to the opening.
      responses:
        '200':
          description: Responses for the opening.addLocation 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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.removeLocation:
    post:
      summary: opening.removeLocation
      description: "Removes a location from an opening.\n      \n**Requires the [`jobsWrite`](authentication#permissions-openingremovelocation) permission.**"
      operationId: openingremovelocation
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - openingId
              - locationId
              properties:
                openingId:
                  type: string
                  description: The id of the opening
                locationId:
                  type: string
                  description: The id of the location to remove from the opening.
      responses:
        '200':
          description: Responses for the opening.removeLocation 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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.setOpeningState:
    post:
      summary: opening.setOpeningState
      description: "Sets the state of an opening.\n      \n**Requires the [`jobsWrite`](authentication#permissions-openingsetopeningstate) permission.**"
      operationId: openingsetopeningstate
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                openingId:
                  type: string
                  description: The id of the opening you want to update
                openingState:
                  type: string
                  description: The new state you want to update the opening to
                  enum:
                  - Draft
                  - Approved
                  - Open
                  - Closed
                closeReasonId:
                  type: string
                  description: The id of the close reason if you are setting the state to closed
      responses:
        '200':
          description: Responses for the opening.setOpeningState 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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.setArchived:
    post:
      summary: opening.setArchived
      description: "Sets the archived state of an opening.\n      \n**Requires the [`jobsWrite`](authentication#permissions-openingsetarchived) permission.**"
      operationId: openingsetarchived
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                openingId:
                  type: string
                  description: The id of the opening you want to archive
                archive:
                  type: boolean
                  description: The new archived state you want to update the opening to
      responses:
        '200':
          description: Responses for the opening.setArchived 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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /opening.update:
    post:
      summary: opening.update
      description: "Updates an opening.\n      \n**Requires the [`jobsWrite`](authentication#permissions-openingupdate) permission.**\n\nTo set values for custom fields on Openings, use the [`customFields.setValue`](https://developers.ashbyhq.com/reference/customfieldsetvalue) endpoint."
      operationId: openingupdate
      tags:
      - Openings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                openingId:
                  type: string
                  description: The openingId of the opening you want to update.
                identifier:
                  type: string
                  description: jobIds,     targetHireDate,     targetStartDate,     isBackfill,     employmentType,
                description:
                  type: string
                teamId:
                  type: string
                  description: The id of the department or team associated with the opening.
                targetHireDate:
                  type: string
                  description: The date (in YYYY-MM-DD format) by which you intend to hire against this opening.
                targetStartDate:
                  type: string
                  description: The date (in YYYY-MM-DD format) by which you intend someone hired against this opening will start employment.
                isBackfill:
                  type: boolean
                  description: Whether this opening is intended to backfill a previous employee
                  default: false
                employmentType:
                  type: string
                  description: The employment type for this opening
                  default: FullTime
                  enum:
                  - FullTime
                  - PartTime
                  - Intern
                  - Contract
                  - Temporary
                  - ''
      responses:
        '200':
          description: Responses for the opening.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/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                    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.