How-to guide
Approve a change as the second person
Find a waiting request, read why it waits, and approve or reject it as a reviewer or admin who did not ask for it.
This guide shows how to approve or reject a change that another person asked for. You need a reviewer or admin account. Changes to policy and to accounts need an admin. You cannot decide a request that you made yourself.
Before you start#
- A request is waiting. It appears when a first person decides a hold above the limit, or changes policy or an account. See Second-person approval for when this happens.
- You are a different person from the one who asked. If you are the same person, the answer is
403 same_person.
The person who asked sees 202 and a body like this:
{
"status": "pending_approval",
"message": "This change needs a second person. It is waiting for approval.",
"approval_id": "44f468b3-befb-47fd-ad36-ef17c8683253",
"reasons": ["The amount 5,400.00 SAR is above the limit of 5,000.00 SAR."]
}Steps#
- List the waiting requests with
GET /api/v1/approvals/?status=pending. - Read the
summaryandreasonsof each one. The summary names the change, for exampleApprove hold 7bbf1052 (Store 3, 5,400.00 SAR). UseGET /api/v1/approvals/{id}/for one request. - Check the facts behind it. For a hold, read the hold with
GET /api/v1/holds/{id}/as in Review a hold. - Send your decision with
POST /api/v1/approvals/{id}/decision/.
curl -X POST https://API/api/v1/approvals/$APPROVAL_ID/decision/ \
-H "Authorization: Bearer yq_live_..." -H "Content-Type: application/json" \
-d '{"decision":"approve","note":"Checked the evidence."}'Use approve or reject. A note is required when you reject.
You cannot change what was asked. You can only approve it as it is, or reject it.
What you see now#
If you approved, the response shows "status": "approved" and a result such as The hold is approved. The payout is held until 2026-11-23. The change ran with the person who asked as the actor. For a hold, decided_by shows that first person. The audit log records both of you.
If you rejected, status is rejected, the result is Rejected by the second person. and nothing changed.
The status can also be failed, with the reason in result. This happens when the change no longer fits the data, for example when the hold was decided in the meantime.
Waiting requests end#
A request waits 24 hours by default. After that its status is cancelled and the result says Expired without a second person. An admin sets the time with expiry_hours (1 to 168) in PUT /api/v1/approvals/settings/. The person who asked, or an admin, can cancel a request earlier with POST /api/v1/approvals/{id}/cancel/.
A team with nobody else who could approve is not locked out. The change then runs at once, and the audit log shows it.
If it does not work#
403 same_person: you asked for this change. Ask another reviewer or admin.403: your role cannot approve this kind of change. Policy and account changes need an admin.400 note_required: add a note to your rejection.409 not_pending: the request is already decided, cancelled or expired. List the requests again.
For more, see Troubleshooting.
Next steps#
- Review a hold: the decision that most often waits for a second person.
- Invite users and set roles: account changes also need a second person.
- Second-person approval: why the rule exists and where the limits are set.
- Settings: the limits and the expiry time.