---
title: Approvals Overview
slug: approvals-overview
docTags: 
createdAt: 2026-09-04T04:17:01.816Z
---

The Approvals API lets you drive Nue Approvals Pro programmatically: discover which approval process applies to a record, preview the approval path before submitting, and submit, approve, reject, recall, or reassign approvals from your own application.

The API runs on the same approval engine as the Approvals Pro UI. A quote submitted through the API follows the same paths, steps, approvers, and record-locking rules as one submitted by a sales rep, and appears in the same approval history. Nothing about how you configure approvals changes.

:::hint{type="info"}
**Availability**

The Approvals API is available in Nue release **2636**.
:::

:::hint{type="info"}
**Required Permission**

Your API key must be associated with a role that has permission to view and act on approvals under the "Nue on Salesforce" category. Requests are executed against a Salesforce session, so the acting user must also be able to see the underlying record.
:::

## Endpoints

| Endpoint                  | Method | Description                                          |
| ------------------------- | ------ | ---------------------------------------------------- |
| `/cpq/approval-processes` | GET    | List the approval processes configured for an object |
| `/cpq/approvals:preview`  | POST   | Preview the approval path without submitting         |
| `/cpq/approvals:submit`   | POST   | Submit a record for approval                         |
| `/cpq/approvals:recall`   | POST   | Recall a submitted record so it can be edited        |
| `/cpq/approvals:approve`  | POST   | Approve one or more pending approvals                |
| `/cpq/approvals:reject`   | POST   | Reject one or more pending approvals                 |
| `/cpq/approvals:reassign` | POST   | Route pending approvals to a different approver      |
| `/cpq/approval-requests`  | GET    | Get approval status for a record                     |
| `/cpq/approvals`          | GET    | List an approver's pending approvals                 |

Read operations are plain `GET` requests. Actions use colon-verb routes, matching the convention used elsewhere in the CPQ API such as `POST /cpq/quotes:preview`.

## Authentication

Include your API key in the request header:

```bash
curl -X POST 'https://api.nue.io/cpq/approvals:preview' \
  -H 'nue-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json'
```

## The Response Envelope

Every endpoint returns the same envelope, whether it succeeds or fails:

```json
{
  "status": "SUCCESS",
  "data": { },
  "warnings": [],
  "errors": []
}
```

| Field      | Type   | Description                        |
| ---------- | ------ | ---------------------------------- |
| `status`   | string | `SUCCESS` or `FAILURE`             |
| `data`     | object | The typed payload for the endpoint |
| `warnings` | array  | Non-fatal messages                 |
| `errors`   | array  | Coded failures. Empty on success   |

Each entry in `warnings` and `errors` has `severity`, `code`, and `message`:

```json
{
  "status": "FAILURE",
  "data": null,
  "warnings": [],
  "errors": [
    {
      "severity": "ERROR",
      "code": "MISSING_PARAMETER",
      "message": "recordId is required"
    }
  ]
}
```

Codes are stable; message text is not. Branch on `code` rather than matching message strings.

:::hint{type="info"}
**Validation failures return the same envelope**

A request that fails validation returns HTTP 400 with the envelope above and a `MISSING_PARAMETER` or `INVALID_PARAMETER` error, not a generic error body. You can parse every response the same way.
:::

## A Typical Flow

1. **Discover** which process applies, if you don't already know: `GET /cpq/approval-processes?recordId={quoteId}`
2. **Preview** the path so you can show the rep what approvals the quote will need: `POST /cpq/approvals:preview`
3. **Submit** the quote when the rep is ready: `POST /cpq/approvals:submit`
4. **Track** where it stands: `GET /cpq/approval-requests?recordId={quoteId}`
5. **Act** as approvals come due: `POST /cpq/approvals:approve` or `:reject`

Step 2 is the one most worth building in. Because a preview writes nothing, you can call it as the rep edits a quote and warn them that a discount will pull in a VP approval while the number can still be changed.

## Recording the Channel

Every action endpoint accepts an optional `source` describing where the request came from, recorded on the approval so an auditor can distinguish a human approval from a programmatic one. It must be one of:

`UI` · `Email` · `API` · `Flow`

Any other value is rejected with `INVALID_PARAMETER`. When you omit it, the action records `API`.

## Acting on Behalf of Another User

The `approve`, `reject`, `recall`, and `reassign` endpoints accept an optional `actor` — a Salesforce User ID to act as. Use it when a service integration completes an action a specific person authorized. The approval history records the actor, so the audit trail names a person rather than the integration.

## Apex

The same nine operations are available as Apex global methods on `appro.GlobalApprovalServiceAPI` for logic running inside Salesforce. The inputs and field shapes match; the only difference is that Apex returns `SUCCEED` where REST returns `SUCCESS`.