Working a quote through the API
Each section below covers one step of the quote lifecycle and the API calls that do what a rep or approver does in the app.
Approve and reject
Approvers can decide on an approval request from your own system, the same way they use the Approve and Reject buttons in Dealops.
| Call | What it does |
|---|---|
POST /approvals/{id}/approve | Approves the request for the current approval group. |
POST /approvals/{id}/reject | Rejects the request. This ends it. |
GET /approvals/actions/{id} | Reports whether a queued decision has been applied. |
POST /approvals/{id}/undo | Takes back a decision within a few seconds of making it. |
Who can decide. All four calls need the approval_request:write scope. A decision is made as the user the API key belongs to, and that user must be an approver in the request's current approval group. There is no admin override over the API.
Not during e-signature. The app hides Approve and Reject while the quote has an e-signature request out or signed, so both are refused then too. It is allowed again once the envelope is voided or declined, or a HelloSign request expires or errors.
Only the current request. The app shows Approve and Reject only on a quote's current approval request. If the quote is submitted again, the new request replaces the old one, and the old one can no longer be decided.
One decision at a time. After you decide, the app shows only Undo until the decision is applied. Likewise, a new decision is refused while one you made on the same request is still queued. Undo it first, or wait for it to be applied.
Explanation. Both decisions take an optional explanation, written in Markdown. It is posted as a comment on the quote. On a rejection, it is also included in the notice sent to the person who submitted the quote.
Auto-approve better quotes. An approval takes an optional autoApproveBetterQuotes, the app's checkbox of the same name, which is on by default. When it's on, your approval becomes a smart approvals precedent: if the deal comes back for approval with terms at least as good on everything your approval group reviews, your step passes automatically. Set it to false to be asked again. It's ignored when your organization doesn't use smart approvals.
Decisions are queued. The call returns straight away with a pendingApprovalActionId. Dealops applies the decision about 4 seconds later, which is the same undo window the app gives. Use that id to check the status or to undo.
After a rejection. There is no "request changes" state. The rejected request stays on the quote until the rep recalls it. To try again, the rep recalls it, revises the quote and submits it again.
Reject a request
curl -X POST https://api.dealops.com/external/v1/approvals/$APPROVAL_REQUEST_ID/reject \
-H "x-api-key: $DEALOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"explanation": "The discount is deeper than Q4 guidance allows."}'
{
"success": true,
"pendingApprovalActionId": "4b6f0c2e-7d1a-4c55-9a43-2f8e1d0b9c71"
}
Approving works the same way, with /approve in place of /reject.
Check that it was applied
curl https://api.dealops.com/external/v1/approvals/actions/$PENDING_APPROVAL_ACTION_ID \
-H "x-api-key: $DEALOPS_API_KEY"
{
"pendingApprovalActionId": "4b6f0c2e-7d1a-4c55-9a43-2f8e1d0b9c71",
"status": "PROCESSED",
"failureReason": null
}
status is one of:
| Status | Meaning |
|---|---|
PENDING | Waiting out the undo window. |
PROCESSING | Being applied now. |
PROCESSED | Applied. The request shows the decision. |
CANCELLED | Undone. Nothing changed. |
FAILED | Could not be applied. failureReason says why. |
Poll every second or two until the status is PROCESSED, CANCELLED or FAILED. Then GET /approvals/{id} shows the request with its new status, such as REJECTED.
Undo a decision
curl -X POST https://api.dealops.com/external/v1/approvals/$PENDING_APPROVAL_ACTION_ID/undo \
-H "x-api-key: $DEALOPS_API_KEY"
The {id} here is the pendingApprovalActionId, not the approval request id. Once the 4 seconds have passed the decision can no longer be undone, and the call returns 400.
Errors when approving or rejecting
| Status | When |
|---|---|
400 | The body is malformed. |
403 | The key lacks approval_request:write, or the key's user is not an approver in the request's current group. |
404 | There is no approval request with that id in your organization. |
409 | The request has already been approved, rejected or recalled, the quote has been submitted again so the request is no longer its current one, or your earlier decision on the request is still queued. message says which. |
412 | The quote is out for signature or signed. |
See Errors for the error body format.