Handle approvals

When a company requires approval for job changes or terminations, your integration's changes become requests. Here is how to propose them, follow them and react when they're decided.

1. Know the rules#

org.approvals.settings.get says, for job changes, terminations and pay, whether approval is off, hr, manager or manager_then_hr (Approvals).

2. Propose a change#

Call the write as usual. Preview it first: the dry run's approval tells you whether it would apply or become a request.

curl https://api.bizisy.com/v1/org/people.change_job \
  -H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id": "p1", "effective_date": "2026-11-01", "reason": "promotion", "title": "Senior Engineer"}'

const { approval } = result; // from the response's data
if (approval === null) {
  // Applied: the job changes on effective_date.
} else if (approval.status === 'pending') {
  // A request: waiting for approval.waiting_for ('manager' or 'hr'); approval.approvers says who can decide.
  await saveRequest(approval.id);
} else {
  // approval.status === 'approved' && approval.automatic: no one else could approve, so it applied.
}

A person can have one open job change request at a time: a second one is refused until the first is decided or withdrawn.

3. Follow it#

• Subscribe to the approval.decided webhook: status is approved (and the person event, such as person.job_changed, follows) or rejected.
• Or read it: org.approvals.get with approval_id, or org.approvals.list for open requests.

Nothing is sent while a request waits, and withdrawing sends nothing.

4. Withdraw it if plans change#

org.approvals.cancel withdraws a waiting request: nothing changes on the person. It works through a key for job and termination requests.

What your integration can't do#

Approve or reject: those need the approver signed in to Bizisy (org.approvals.approve refuses keys and connected apps). Nor can it change who approves. Point people to Approvals in Bizisy; approvers also see waiting requests on their Home.

Pay changes are recorded only in the app, so pay change requests never come from a key.