---
title: "approvalDefinition.update"
method: POST
path: "/approvalDefinition.update"
tags: ["Approval Definition"]
---

# approvalDefinition.update

`POST /approvalDefinition.update`

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.**

## Request body

- ApprovalDefinitionUpdateRequest
  - `entityType` 'offer', required — The type of approval entity being updated.
  - `entityId` string, uuid, required — The id of the approval entity being updated, such as the id of the offer version.
  - `approvalStepDefinitions` ApprovalStepDefinition[], required — 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.
    - `approvalsRequired` integer, required — 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-negative and no more than the number of approvers in this step.
    - `approvers` ApprovalStepDefinitionApproverUser[], required — An unordered list of who can approve this step.
      - `userId` string, uuid, required — The id of a user who is an approver for this step.
      - `type` 'user', required — The type of approver.
  - `submitApprovalRequest` boolean, nullable — 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. Defaults to false.

## Response `200`

Responses from the approvalDefinition.update endpoint

- union
  - union
    - ApprovalDefinitionUpdateSuccessResponse
      - `success` true, required
      - `results` ApprovalDefinition, required
        - `id` string, uuid, required — The id of the approval definition.
        - `entityType` 'Offer', required — The type of approval entity.
        - `entityId` string, uuid, required — The id of the approval entity, such as the id of the offer version.
        - `approvalSteps` ApprovalStepDefinition[], required — 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.
          - `approvalsRequired` integer, required — 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-negative and no more than the number of approvers in this step.
          - `approvers` ApprovalStepDefinitionApproverUser[], required — An unordered list of who can approve this step.
            - `userId` string, uuid, required — The id of a user who is an approver for this step.
            - `type` 'user', required — The type of approver.
    - ApprovalDefinitionUpdateSkipSuccessResponse
      - `success` true, required
  - ErrorResponse
    - `success` false, required
    - `errors` ErrorDetail[], required
      - `message` string, required
      - `parameter` string

---

[API](https://skmtc.net/ashbyhq/apis/ashby-api.md) · [All operations](https://skmtc.net/ashbyhq/apis/ashby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ashbyhq/ashby-api/revisions/778b919dc743/schema)