openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Approval Definition 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: Approval Definition
paths:
  /approvalDefinition.update:
    post:
      summary: approvalDefinition.update
      operationId: approvalDefinitionUpdate
      description: 'Create or update an approval definition for a specific entity that requires approval. The entity requiring approval must be within scope of an approval in Ashby that is marked as being managed by the API.


        If the provided approval step definitions is an empty list, then approval will be skipped and the entity will proceed to the next stage.


        **Requires the [`approvalsWrite`](authentication#permissions-approvaldefinitionupdate) permission.**

        '
      tags:
      - Approval Definition
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entityType:
                  type: string
                  enum:
                  - offer
                entityId:
                  allOf:
                  - description: The id of the approval entity being updated (e.g. the id of the offer version).
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                approvalStepDefinitions:
                  type: array
                  description: An ordered list of approval steps that describes the number of required approvers at each step, as well as who is an approver at each step.
                  items:
                    type: object
                    properties:
                      approvalsRequired:
                        type: integer
                        description: The number of approvers required to approve this step, before the approval moves on to the next step. The number of approvers must be non-zero and no more than the number of approvers in this step.
                        example: 1
                      approvers:
                        type: array
                        description: An unordered list of who can approve this step.
                        items:
                          type: object
                          properties:
                            userId:
                              allOf:
                              - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                              - description: The id of a user who is an approver for this step.
                            type:
                              type: string
                              enum:
                              - user
                          required:
                          - userId
                          - type
                    required:
                    - approvalsRequired
                    - approvers
                submitApprovalRequest:
                  type: boolean
                  description: 'Control whether an approval request created through this API should be immediately submitted.

                    If false, then the approval will need to be manually submitted in the Ashby app.

                    Default: false

                    '
              required:
              - entityType
              - entityId
              - approvalStepDefinitions
      responses:
        '200':
          description: Responses from the approvalDefinition.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:
                        type: object
                        properties:
                          id:
                            allOf:
                            - description: The id of the approval definition.
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          entityType:
                            type: string
                            enum:
                            - Offer
                          entityId:
                            allOf:
                            - description: The id of the approval entity (e.g. the id of the offer version).
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          approvalStepDefinitions:
                            $ref: '#/paths/~1approvalDefinition.update/post/requestBody/content/application~1json/schema/properties/approvalStepDefinitions'
                        required:
                        - entityType
                        - entityId
                        - approvalStepDefinitions
                    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.