Supply Chain · Requisitions & Orders
PO Approval Rules
Which purchase orders need approval, and who signs. A rule on the buyer's reporting line follows the HRMS Organization Chart (and the position tree where a manager is not recorded), so reorganising the company re-routes approvals with nothing to change here.
/api/scm/po-approval-rulesPublished as /api/v1/po-approval-rulesDownload specification (OpenAPI 3.1) Screen: PO Approval Rules
Overview
| Package | Supply Chain |
|---|---|
| Authentication | Bearer token: a service account's token (POST /api/auth/service-token) or, for the published path, an API key |
| Authorization | The caller's roles must hold Supply Chain › PO Approval Rules on the Roles screen: display for GET, add for POST, change for PUT, delete for DELETE; an action needs the grant of the button that runs it on the screen. |
| Table | scm.po_approval_rules · kept per company (and organisational unit where it has one) |
| Record | Created, changed and (where the screen allows) deleted; key id |
| Rules | The same as the screen: validation, numbering, approvals, posting, the company the caller belongs to, and the audit trail. |
API reference
12 operations. Open one for its parameters, bodies, responses and a sample request.
GET/api/scm/po-approval-rulesList po approval rules
Query parameters
| Name | Description | Example |
|---|---|---|
limit | Rows per page (50 by default, at most 200) | limit=100 |
offset | Rows to skip | offset=200 |
q | Free-text search over the search columns | q=acme |
sort | column:asc or column:desc, several separated by commas | sort=created_at:desc |
filter | A JSON condition or group (see the filter language), URL-encoded; any field below can be filtered and sorted | filter={"col":"status","op":"eq","value":"open"} |
<field>=<value> | Shorthand for "field is value" |
Response 200
{
"rows": [
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"code": "COD-000001",
"name": "Example",
"priority": 10,
"amount_threshold": "1250.00",
"supplier_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"approver_kind": "A named person (their sign-in) — no HRMS needed",
"levels": 10,
"approver_role": "text",
"approver_employee_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"due_in_hours": 10,
"is_active": true,
"description": "text"
}
],
"count": 1
}Sample request
curl "https://demo.tranxact.ai/api/scm/po-approval-rules?limit=20" \
-H "Authorization: Bearer $TOKEN"GET/api/scm/po-approval-rules/{id}Read one approval rule
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response 200
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"code": "COD-000001",
"name": "Example",
"priority": 10,
"amount_threshold": "1250.00",
"supplier_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"approver_kind": "A named person (their sign-in) — no HRMS needed",
"levels": 10,
"approver_role": "text",
"approver_employee_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"due_in_hours": 10,
"is_active": true,
"description": "text"
}404 when no record with that id is visible to the caller.
Sample request
curl "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"POST/api/scm/po-approval-rulesCreate a approval rule
Request body
The record as JSON. Fields marked Yes are required.
| Field | Type | Required | Description |
|---|---|---|---|
code | text | Yes | Code |
name | text | Yes | Name |
priority | integer | No | Order — Every rule that matches applies; lower numbers collect their signatures first. |
amount_threshold | numeric | No | Applies from amount (inclusive) — In the company's own currency: an order is judged on its total converted at its exchange rate, so a EUR and an INR order meet the same limit. 0 means every purchase order. An order no rule covers is released without approval: "Amounts covered" shows any gap. |
supplier_id | uuid | No | Only for supplier |
approver_kind | text | No | Who approves — Choose one. Only the field for that choice is needed below. Everything above it — amount, supplier, cost center, unit — is optional and only narrows which orders the rule covers. "The cost center’s manager": The manager recorded on the cost center (Accounting › Controlling › Cost Centers): its HRMS manager, or else its responsible person. Allowed: A named person (their sign-in) — no HRMS needed An employee (HRMS) Whoever holds a position (HRMS) Anyone holding a role The cost center’s manager The reporting line of whoever raised it (HRMS) |
levels | integer | No | Levels up the reporting line — 1 is the buyer's manager, 2 adds their manager, up to 5. Needs, in HRMS: the person who raises the order linked to their employee record ("Signs in as" on the employee), and that employee given a manager on the Organization Chart (or a position whose parent position somebody holds). No cost center is needed. An order raised before the link was made is routed again as soon as the link or the manager is saved. |
approver_role | text | No | Role — For "anyone holding a role". On a reporting-line rule it is the last resort: used when neither the reporting line nor the employee below gives anybody. |
approver_employee_id | uuid | No | Employee — For "an employee". On a reporting-line rule, the approver when the buyer has no reporting line in HRMS. An employee with no sign-in yet is still the approver; the order waits for them. |
due_in_hours | integer | No | Due within (hours) |
is_active | boolean | No | Active |
description | text | No | Description |
uses_levels | boolean | No | Name the approvers level by level — On: the rule uses its own Approval Levels — named people in order, the absent skipped, delegations followed. Off: the single approver above, repeated for as many levels as it says. |
cost_center_id | uuid | No | Only for cost center — Orders charged to this cost center, on the order or on any of its lines. Leave empty for every cost center. For two cost centers, make one rule for each. |
approver_user_id | uuid | No | Person — Anyone who signs in to this company. They decide it from My approvals, whatever modules they have. |
approver_position_id | uuid | No | Position — Whoever holds this position in HRMS when the document is sent. When somebody else takes the post, new documents go to them with nothing to change here. |
po_type_id | uuid | No | Po type id |
Sample body
{
"code": "COD-000001",
"name": "Example",
"priority": 10,
"amount_threshold": "1250.00",
"supplier_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"approver_kind": "A named person (their sign-in) — no HRMS needed"
}Response 201
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"code": "COD-000001",
"name": "Example",
"priority": 10,
"amount_threshold": "1250.00",
"supplier_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"approver_kind": "A named person (their sign-in) — no HRMS needed",
"levels": 10,
"approver_role": "text",
"approver_employee_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"due_in_hours": 10,
"is_active": true,
"description": "text"
}Sample request
curl -X POST "https://demo.tranxact.ai/api/scm/po-approval-rules" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"code":"COD-000001","name":"Example","priority":10,"amount_threshold":"1250.00","supplier_id":"3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73","approver_kind":"A named person (their sign-in) — no HRMS needed"}'PUT/api/scm/po-approval-rules/{id}Change a approval rule
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
Only the fields to change; fields left out keep their value.
| Field | Type | Required | Description |
|---|---|---|---|
code | text | Yes | Code |
name | text | Yes | Name |
priority | integer | No | Order — Every rule that matches applies; lower numbers collect their signatures first. |
amount_threshold | numeric | No | Applies from amount (inclusive) — In the company's own currency: an order is judged on its total converted at its exchange rate, so a EUR and an INR order meet the same limit. 0 means every purchase order. An order no rule covers is released without approval: "Amounts covered" shows any gap. |
supplier_id | uuid | No | Only for supplier |
approver_kind | text | No | Who approves — Choose one. Only the field for that choice is needed below. Everything above it — amount, supplier, cost center, unit — is optional and only narrows which orders the rule covers. "The cost center’s manager": The manager recorded on the cost center (Accounting › Controlling › Cost Centers): its HRMS manager, or else its responsible person. Allowed: A named person (their sign-in) — no HRMS needed An employee (HRMS) Whoever holds a position (HRMS) Anyone holding a role The cost center’s manager The reporting line of whoever raised it (HRMS) |
levels | integer | No | Levels up the reporting line — 1 is the buyer's manager, 2 adds their manager, up to 5. Needs, in HRMS: the person who raises the order linked to their employee record ("Signs in as" on the employee), and that employee given a manager on the Organization Chart (or a position whose parent position somebody holds). No cost center is needed. An order raised before the link was made is routed again as soon as the link or the manager is saved. |
approver_role | text | No | Role — For "anyone holding a role". On a reporting-line rule it is the last resort: used when neither the reporting line nor the employee below gives anybody. |
approver_employee_id | uuid | No | Employee — For "an employee". On a reporting-line rule, the approver when the buyer has no reporting line in HRMS. An employee with no sign-in yet is still the approver; the order waits for them. |
due_in_hours | integer | No | Due within (hours) |
is_active | boolean | No | Active |
description | text | No | Description |
uses_levels | boolean | No | Name the approvers level by level — On: the rule uses its own Approval Levels — named people in order, the absent skipped, delegations followed. Off: the single approver above, repeated for as many levels as it says. |
cost_center_id | uuid | No | Only for cost center — Orders charged to this cost center, on the order or on any of its lines. Leave empty for every cost center. For two cost centers, make one rule for each. |
approver_user_id | uuid | No | Person — Anyone who signs in to this company. They decide it from My approvals, whatever modules they have. |
approver_position_id | uuid | No | Position — Whoever holds this position in HRMS when the document is sent. When somebody else takes the post, new documents go to them with nothing to change here. |
po_type_id | uuid | No | Po type id |
Sample body
{
"code": "COD-000001",
"name": "Example"
}Response 200
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"code": "COD-000001",
"name": "Example",
"priority": 10,
"amount_threshold": "1250.00",
"supplier_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"approver_kind": "A named person (their sign-in) — no HRMS needed",
"levels": 10,
"approver_role": "text",
"approver_employee_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"due_in_hours": 10,
"is_active": true,
"description": "text"
}Sample request
curl -X PUT "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"code":"COD-000001","name":"Example"}'DELETE/api/scm/po-approval-rules/{id}Delete a approval rule
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response 200
{ "deleted": true }Many documents are cancelled or reversed instead; the API refuses a delete the screen would refuse.
Sample request
curl -X DELETE "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"POST/api/scm/po-approval-rules/ladderLadder
Request body
The keys this action reads (* = required; "one of" lists the only values):
rule*, preview; levels*: [{ approver_kind, name, approver_employee_id, approver_user_id, approver_position_id, approver_role, amount_threshold, due_in_hours, may_skip_if_absent, level_no, who }]Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/scm/po-approval-rules/ladder" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"rule":"value","preview;":"value","name":"value","approver_employee_id":"value","approver_user_id":"value","approver_position_id":"value"}'GET/api/scm/po-approval-rules/{id}/level-historyLevel history
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response
200 with the data as JSON.
Sample request
curl "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/level-history" \
-H "Authorization: Bearer $TOKEN"POST/api/scm/po-approval-rules/{id}/copyCopy
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
overrides, preview, withLinesResponse
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copy" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"overrides":"value","preview":"value","withLines":"value"}'GET/api/scm/po-approval-rules/{parentId}/copiesCopies
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
Response
200 with the data as JSON.
Sample request
curl "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copies" \
-H "Authorization: Bearer $TOKEN"POST/api/scm/po-approval-rules/{parentId}/copiesCopies
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copies" \
-H "Authorization: Bearer $TOKEN"PUT/api/scm/po-approval-rules/{parentId}/copies/{lineId}Copies
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
lineId | string (uuid) | The record's lineId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X PUT "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copies/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"DELETE/api/scm/po-approval-rules/{parentId}/copies/{lineId}Copies
Path parameters
| Name | Type | Description |
|---|---|---|
parentId | string (uuid) | The record's parentId, as a list returns it. |
lineId | string (uuid) | The record's lineId, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X DELETE "https://demo.tranxact.ai/api/scm/po-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copies/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"Data model
Every field of a approval rule, as the API returns it. Field names are the JSON keys; any of them can be filtered and sorted on a list.
| Field | Type | Access | Description |
|---|---|---|---|
id | uuid | read only | Id |
org_id | uuid | read only | Org id |
org_unit_id | uuid | read only | Organizational unit — The orders of this unit and every unit beneath it. The top of the company means every purchase order. Saving the rule routes the open orders it now decides again. |
code | text | read, write | Code |
name | text | read, write | Name |
priority | integer | read, write | Order — Every rule that matches applies; lower numbers collect their signatures first. |
amount_threshold | numeric | read, write | Applies from amount (inclusive) — In the company's own currency: an order is judged on its total converted at its exchange rate, so a EUR and an INR order meet the same limit. 0 means every purchase order. An order no rule covers is released without approval: "Amounts covered" shows any gap. |
supplier_id | uuid | read, write | Only for supplier |
approver_kind | text | read, write | Who approves — Choose one. Only the field for that choice is needed below. Everything above it — amount, supplier, cost center, unit — is optional and only narrows which orders the rule covers. "The cost center’s manager": The manager recorded on the cost center (Accounting › Controlling › Cost Centers): its HRMS manager, or else its responsible person. Allowed: A named person (their sign-in) — no HRMS needed An employee (HRMS) Whoever holds a position (HRMS) Anyone holding a role The cost center’s manager The reporting line of whoever raised it (HRMS) |
levels | integer | read, write | Levels up the reporting line — 1 is the buyer's manager, 2 adds their manager, up to 5. Needs, in HRMS: the person who raises the order linked to their employee record ("Signs in as" on the employee), and that employee given a manager on the Organization Chart (or a position whose parent position somebody holds). No cost center is needed. An order raised before the link was made is routed again as soon as the link or the manager is saved. |
approver_role | text | read, write | Role — For "anyone holding a role". On a reporting-line rule it is the last resort: used when neither the reporting line nor the employee below gives anybody. |
approver_employee_id | uuid | read, write | Employee — For "an employee". On a reporting-line rule, the approver when the buyer has no reporting line in HRMS. An employee with no sign-in yet is still the approver; the order waits for them. |
due_in_hours | integer | read, write | Due within (hours) |
is_active | boolean | read, write | Active |
description | text | read, write | Description |
created_at | timestamp with time zone | read only | Created at |
uses_levels | boolean | read, write | Name the approvers level by level — On: the rule uses its own Approval Levels — named people in order, the absent skipped, delegations followed. Off: the single approver above, repeated for as many levels as it says. |
xf_text_1 | text | read only | Xf text 1 |
xf_text_2 | text | read only | Xf text 2 |
xf_text_3 | text | read only | Xf text 3 |
xf_text_4 | text | read only | Xf text 4 |
xf_text_5 | text | read only | Xf text 5 |
xf_num_1 | numeric | read only | Xf num 1 |
xf_num_2 | numeric | read only | Xf num 2 |
xf_num_3 | numeric | read only | Xf num 3 |
xf_date_1 | date | read only | Xf date 1 |
xf_date_2 | date | read only | Xf date 2 |
created_by | uuid | read only | Created by |
updated_at | timestamp with time zone | read only | Updated at |
updated_by | uuid | read only | Updated by |
cost_center_id | uuid | read, write | Only for cost center — Orders charged to this cost center, on the order or on any of its lines. Leave empty for every cost center. For two cost centers, make one rule for each. |
approver_user_id | uuid | read, write | Person — Anyone who signs in to this company. They decide it from My approvals, whatever modules they have. |
approver_position_id | uuid | read, write | Position — Whoever holds this position in HRMS when the document is sent. When somebody else takes the post, new documents go to them with nothing to change here. |
po_type_id | uuid | read, write | Po type id |
Errors
| Status | Meaning |
|---|---|
| 400 | The request could not be read: a filter that is not JSON, a bad parameter |
| 401 | No credential, or it is wrong, revoked or expired |
| 403 | The caller's roles do not hold Supply Chain › PO Approval Rules for this verb, or the address or origin is not allowed |
| 404 | No record with that id is visible to the caller |
| 409 | A conflict: a duplicate number, a document in a state that does not allow it, or a record changed or locked by someone else |
| 422 | Refused by the same validation as the screen; the error names the field and why |
Every error is JSON: {"error": "a sentence saying what was wrong"}, with field where it applies.