Preview and Submit Approvals

11 min

This guide covers the read-then-submit half of the Approvals API: finding the applicable process, previewing the approval path, submitting a record, and recalling it if it needs to change.

List Approval Processes

Returns the approval processes configured for an object, in the order the approval engine evaluates them.

GET /cpq/approval-processes

Parameter	Type	Description
objectType	string	Object to list processes for, for example Quote. Required unless recordId is supplied
recordId	string	Derives the object from a record and returns only processes applicable to that record
activeOnly	boolean	Return only active processes

curl -X GET 'https://api.nue.io/cpq/approval-processes?objectType=Quote&activeOnly=true' \
  -H 'nue-api-key: YOUR_API_KEY'

{
  "status": "SUCCESS",
  "data": {
    "objectType": "Quote",
    "processes": [
      {
        "processName": "Standard Discount Approval",
        "objectType": "Quote",
        "versionNumber": 3,
        "isActive": true,
        "processOrder": 1,
        "appliesWhen": "Discount greater than 15%",
        "description": "Routes discounted quotes to the deal desk and above"
      }
    ]
  },
  "warnings": [],
  "errors": []
}

Supply recordId instead of objectType when you want only the processes that actually apply to one record.

Preview the Approval Path

Returns the routing a record would follow if it were submitted right now. Nothing is written — you can call this as often as you like.

POST /cpq/approvals:preview

Field	Type	Description
recordId	string	Required. The record to preview
processName	string	Omit to let the engine resolve the applicable process

curl -X POST 'https://api.nue.io/cpq/approvals:preview' \
  -H 'nue-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "recordId": "0Q0Kb000000XyZaKAK" }'

{
  "status": "SUCCESS",
  "data": {
    "recordId": "0Q0Kb000000XyZaKAK",
    "requiresApproval": true,
    "resolvedProcessName": "Standard Discount Approval",
    "paths": [
      {
        "pathId": "a0RKb000000TxAbMAK",
        "pathName": "Discount over 15%",
        "willTrigger": true,
        "dependsOnPathId": null,
        "steps": [
          {
            "stepId": "a0SKb000000UvBcMAK",
            "stepName": "Deal Desk",
            "stepStatus": null,
            "triggerReason": "Discount is 22%, threshold is 15%",
            "approvalReason": "Discount approved by deal desk",
            "resolveOn": "AllApprovers",
            "numberOfApprovers": 1,
            "dependsOnStepId": null,
            "isRemembered": false,
            "approvers": [
              {
                "approverType": "User",
                "userId": "005Kb000000WxYzIAK",
                "name": "Dana Reyes",
                "groupOrRoleName": null
              }
            ]
          }
        ]
      }
    ]
  },
  "warnings": [],
  "errors": []
}

Three fields carry most of the value:

requiresApproval — false when no configured path applies. Use it to skip the approval step entirely rather than submitting and discovering nothing happened.

willTrigger on each path, with triggerReason — tells you why a path applies, in terms you can show a rep.

approvers on each step — the people who will actually be asked, resolved from users, groups, or roles.

Preview is the cheapest guardrail you can build

Because it persists nothing, you can call preview on every quote save. Surfacing "this discount needs VP sign-off" while the rep is still editing is far cheaper than discovering it after submission.

Submit for Approval

Submits a record into its approval process. The record is locked according to the process configuration.

POST /cpq/approvals:submit

Field	Type	Description
recordId	string	Required. The record being submitted
processName	string	Omit to let the engine resolve the applicable process
submittedMessage	string	Comment recorded on the submission
source	string	UI, Email, API, or Flow. Defaults to API

curl -X POST 'https://api.nue.io/cpq/approvals:submit' \
  -H 'nue-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recordId": "0Q0Kb000000XyZaKAK",
    "submittedMessage": "Discount approved by regional director on the call",
    "source": "API"
  }'

{
  "status": "SUCCESS",
  "data": {
    "requestId": "a0TKb000000VwCdMAK",
    "recordId": "0Q0Kb000000XyZaKAK",
    "status": "Pending",
    "isLocked": true,
    "approvers": [
      {
        "approvalId": "a0UKb000000WxDeMAK",
        "stepName": "Deal Desk",
        "stepStatus": "Pending",
        "approverUserId": "005Kb000000WxYzIAK",
        "originalApproverUserId": null,
        "reassignedFromApprovalId": null,
        "rejectionMessage": null
      }
    ],
    "approvals": []
  },
  "warnings": [],
  "errors": []
}

isLocked tells you whether the record is now read-only. Reflect it in your UI so a rep isn't offered an edit that will fail.

Recall a Submission

Pulls a submitted record back out of its approval process so it can be edited again, unlocking it and revoking the outstanding approvals.

POST /cpq/approvals:recall

Field	Type	Description
recordId	string	Required. The record whose submission is being recalled
processName	string	Omit to let the engine resolve the applicable process
actor	string	Salesforce User ID to act on behalf of
source	string	UI, Email, API, or Flow. Defaults to API

curl -X POST 'https://api.nue.io/cpq/approvals:recall' \
  -H 'nue-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "recordId": "0Q0Kb000000XyZaKAK" }'

Recall is the supported way to correct a quote mid-approval. Editing around a locked record leaves the approval history inconsistent with what was actually approved.