--- title: "[Beta] Update Template Approval Workflow" method: PUT path: "/public/beta/templates/{template_id}/approval-workflow" tags: ["Approval Workflows"] --- # \[Beta\] Update Template Approval Workflow `PUT /public/beta/templates/{template_id}/approval-workflow` ## Request - Base URL: `https://api.pandadoc.com` - URL: `https://api.pandadoc.com/public/beta/templates/{template_id}/approval-workflow` - Auth: one of: - API key in header `Authorization` - OAuth 2 - Authorization code: `https://app.pandadoc.com/oauth2/authorize` - Token URL: `https://api.pandadoc.com/oauth2/access_token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates or replaces the Submit for approval configuration on a template. A template has at most one configuration; this operation always writes the full desired end-state. `steps` lists the stages in the approval order and must contain at least one stage. The property name stays `steps` so it matches `selected_approvers.steps` on Send Document. Learn more about [approval workflows](https://support.pandadoc.com/en/?q=Approval+workflow). ## Request body - ApprovalWorkflowRequest: Full replacement of the Submit for approval configuration on a template. A template has at most one configuration; this request creates it or replaces the existing one. `steps` lists the stages in the approval order and must contain at least one stage. The property name stays `steps` so it matches `selected_approvers.steps` on Send Document. - `is_enabled` boolean: Whether Submit for approval runs when a document is created from this template. Set to `false` to turn it off while keeping its stages. Defaults to `true` when omitted. - `is_ordering_enabled` boolean: Approval order. When `true`, the document goes to one approver at a time. When `false`, every approver is requested together. Defaults to `true` when omitted. An unconfigured GET returns `false`. That empty state is not this default. Set the field, or omit it, when building a create request from that GET body. - `is_editing_allowed` boolean: Whether the approvers and approval groups can be edited on documents created from this template. - `steps` ApprovalWorkflowStepRequest[], required: Stages in the approval order. Each stage is one approver or one approval group. At least 1 stage, at most 50, and at most 100 approvers across all stages. A stage with one approver counts as one approver. A stage with an approval group counts as each approver in that group. An empty array is rejected. To turn Submit for approval off without dropping its stages, set `is_enabled` to `false`. - union: One stage in the approval order of the Submit for approval configuration. Provide either `assignee` (one approver) or `group` (an approval group), not both. The property name stays `assignee` so it matches `assignees` on Send Document. - object - `assignee` union, required: Identify an approver as a workspace member (`membership_id` or `email`) or as the document sender (`is_document_sender: true`). Provide exactly one of `membership_id` or `email`, unless `is_document_sender` is `true`. When `is_document_sender` is `true`, omit both identifiers. Resolve `membership_id` with List Members. - object - `membership_id` string, required: Workspace membership id from List Members. Not the approver `id` or `user.id` from GET. Copying either of those into this field is rejected. To replace a workflow from a GET response, send `user.email`, or send a membership id from List Members. - `is_document_sender` false: Omit or set to `false` when identifying a workspace member. - `is_selected` boolean: Pre-selects this approver in a selectable group. Ignored when the approver is the whole stage in the approval order, or on a member of any other group type. Responses include this field only for selectable groups. - object - `email` string, email, required: Email of a workspace member. - `is_document_sender` false: Omit or set to `false` when identifying a workspace member. - `is_selected` boolean: Pre-selects this approver in a selectable group. Ignored when the approver is the whole stage in the approval order, or on a member of any other group type. Responses include this field only for selectable groups. - object - `is_document_sender` true, required: When `true`, the document sender is the approver for this stage. Do not set `membership_id` or `email`. - `is_selected` boolean: Pre-selects this approver in a selectable group. Ignored when the approver is the whole stage in the approval order, or on a member of any other group type. Responses include this field only for selectable groups. - `group` ApprovalWorkflowGroupRequest: An approval group for one stage in the approval order. Omit `type` unless the group is Allow user to select approver (`selectable`). When `type` is omitted, every approver in the group is notified and any one approval finishes the stage. The group is still required. - `name` string, required: Display name of the group. - `type` 'selectable': Present only for Allow user to select approver. When `type` is omitted, every approver in the group is notified and any one of them can approve. The group is still required. - `selectable` — Allow user to select approver. The sender chooses one approver from the group in Submit for approval. - `assignees` ApprovalWorkflowAssigneeRequest[], required: Approvers in the group. Must contain unique users. At least one approver, at most 50 per group, and at most 100 approvers across the whole configuration. A group with no approvers can appear on GET and is rejected here. The property name stays `assignees` so it matches Send Document. - union: Identify an approver as a workspace member (`membership_id` or `email`) or as the document sender (`is_document_sender: true`). Provide exactly one of `membership_id` or `email`, unless `is_document_sender` is `true`. When `is_document_sender` is `true`, omit both identifiers. Resolve `membership_id` with List Members. - … - object - `assignee` union: Identify an approver as a workspace member (`membership_id` or `email`) or as the document sender (`is_document_sender: true`). Provide exactly one of `membership_id` or `email`, unless `is_document_sender` is `true`. When `is_document_sender` is `true`, omit both identifiers. Resolve `membership_id` with List Members. - object - `membership_id` string, required: Workspace membership id from List Members. Not the approver `id` or `user.id` from GET. Copying either of those into this field is rejected. To replace a workflow from a GET response, send `user.email`, or send a membership id from List Members. - `is_document_sender` false: Omit or set to `false` when identifying a workspace member. - `is_selected` boolean: Pre-selects this approver in a selectable group. Ignored when the approver is the whole stage in the approval order, or on a member of any other group type. Responses include this field only for selectable groups. - object - `email` string, email, required: Email of a workspace member. - `is_document_sender` false: Omit or set to `false` when identifying a workspace member. - `is_selected` boolean: Pre-selects this approver in a selectable group. Ignored when the approver is the whole stage in the approval order, or on a member of any other group type. Responses include this field only for selectable groups. - object - `is_document_sender` true, required: When `true`, the document sender is the approver for this stage. Do not set `membership_id` or `email`. - `is_selected` boolean: Pre-selects this approver in a selectable group. Ignored when the approver is the whole stage in the approval order, or on a member of any other group type. Responses include this field only for selectable groups. - `group` ApprovalWorkflowGroupRequest, required: An approval group for one stage in the approval order. Omit `type` unless the group is Allow user to select approver (`selectable`). When `type` is omitted, every approver in the group is notified and any one approval finishes the stage. The group is still required. - `name` string, required: Display name of the group. - `type` 'selectable': Present only for Allow user to select approver. When `type` is omitted, every approver in the group is notified and any one of them can approve. The group is still required. - `selectable` — Allow user to select approver. The sender chooses one approver from the group in Submit for approval. - `assignees` ApprovalWorkflowAssigneeRequest[], required: Approvers in the group. Must contain unique users. At least one approver, at most 50 per group, and at most 100 approvers across the whole configuration. A group with no approvers can appear on GET and is rejected here. The property name stays `assignees` so it matches Send Document. - union: Identify an approver as a workspace member (`membership_id` or `email`) or as the document sender (`is_document_sender: true`). Provide exactly one of `membership_id` or `email`, unless `is_document_sender` is `true`. When `is_document_sender` is `true`, omit both identifiers. Resolve `membership_id` with List Members. - … ## Response `200` Successfully created or replaced the Submit for approval configuration. - ApprovalWorkflowResponse: The Submit for approval configuration stored on the template. - `is_enabled` boolean, required: Stored enabled flag. A configuration that is enabled but contains only groups with no approvers is still returned as enabled. An unconfigured template returns `false`. - `is_ordering_enabled` boolean, required: Approval order. When `true`, the document goes to one approver at a time. When `false`, every approver is requested together. On an unconfigured template this is `false` (empty state). Creating a configuration with the field omitted defaults to `true`. - `is_editing_allowed` boolean, required: Whether the approvers and approval groups can be edited on documents created from this template. - `has_conditional_approvals` boolean, required: `true` when an approver or an approval group has conditional approvals. Those conditional approvals are not included in `steps`. PUT on this path is rejected until they are removed in PandaDoc. - `steps` ApprovalWorkflowStepResponse[], required: Stored stages in the approval order, including groups with no approvers. `[]` means the template has no Submit for approval configuration (`is_enabled` is `false`). PUT requires at least one approver in every group, so an empty group from this response must be replaced or dropped before writing. - `id` string, required: Unique identifier of this stage in the approval order. - `assignee` ApprovalWorkflowAssigneeResponse: An approver for a stage in the approval order, or a member of an approval group. `user` is present for a workspace member and omitted when `is_document_sender` is `true`. - `id` string, required: Approver id within the Submit for approval configuration. Not a membership id and not a user id. Do not send this value as `membership_id` on PUT. - `user` ApprovalWorkflowUser: A workspace member who can act as an approver. - `id` string, required: User id. Not a workspace membership id. Do not send this value as `membership_id` on PUT. Use `email` to identify this user on a later PUT. - `email` string, email, required: User email address. - `first_name` string: User first name. - `last_name` string: User last name. - `avatar` string: URL of the user avatar. Omitted when the user has no avatar. - `is_document_sender` boolean, required: Whether this approver is the document sender. - `is_selected` boolean: Whether this approver is pre-selected. Present only for members of a selectable group. - `group` ApprovalWorkflowGroupResponse: An approval group for one stage in the approval order. - `id` string, required: Unique identifier of the group. - `name` string, required: Display name of the group. - `type` 'selectable': Present only for Allow user to select approver. When `type` is omitted, every approver in the group is notified and any one of them can approve. The group is still required. - `selectable` — Allow user to select approver. The sender chooses one approver from the group in Submit for approval. - `assignees` ApprovalWorkflowAssigneeResponse[], required: Approvers in the group. A stored group can have no approvers. PUT requires at least one approver in every group. - `id` string, required: Approver id within the Submit for approval configuration. Not a membership id and not a user id. Do not send this value as `membership_id` on PUT. - `user` ApprovalWorkflowUser: A workspace member who can act as an approver. - `id` string, required: User id. Not a workspace membership id. Do not send this value as `membership_id` on PUT. Use `email` to identify this user on a later PUT. - `email` string, email, required: User email address. - `first_name` string: User first name. - `last_name` string: User last name. - `avatar` string: URL of the user avatar. Omitted when the user has no avatar. - `is_document_sender` boolean, required: Whether this approver is the document sender. - `is_selected` boolean: Whether this approver is pre-selected. Present only for members of a selectable group. ## Other responses - `400`: Bad Request error - `401`: Authentication error - `403`: Permission error - `404`: Not found error - `429`: Too many requests error ## Changes - **2026-11-03** `b9a306b1a421`: 1 info - endpoint added [Operation history](https://skmtc.dev/pandadoc/apis/pandadoc-public-api/changes/public/beta/templates/:template_id/approval-workflow/put.md) --- [API](https://skmtc.dev/pandadoc/apis/pandadoc-public-api.md) - [All operations](https://skmtc.dev/pandadoc/apis/pandadoc-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pandadoc/apis/pandadoc-public-api/revisions/b9a306b1a421?raw)