openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Openings 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: 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`](ref: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`](ref: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: "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.

        '