YaqeenDocs
Back to Yaqeen

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:

json
{
  "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#

  1. List the waiting requests with GET /api/v1/approvals/?status=pending.
  2. Read the summary and reasons of each one. The summary names the change, for example Approve hold 7bbf1052 (Store 3, 5,400.00 SAR). Use GET /api/v1/approvals/{id}/ for one request.
  3. Check the facts behind it. For a hold, read the hold with GET /api/v1/holds/{id}/ as in Review a hold.
  4. Send your decision with POST /api/v1/approvals/{id}/decision/.
bash
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#

Up Down to moveEnter to openEsc to close