openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Approval Definition 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: 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: "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.

        '