TRANXACT.AI Help

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.

Type REST12 operationsBase path /api/scm/po-approval-rulesPublished as /api/v1/po-approval-rules

Download specification (OpenAPI 3.1) Screen: PO Approval Rules

Overview

PackageSupply Chain
AuthenticationBearer token: a service account's token (POST /api/auth/service-token) or, for the published path, an API key
AuthorizationThe 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.
Tablescm.po_approval_rules · kept per company (and organisational unit where it has one)
RecordCreated, changed and (where the screen allows) deleted; key id
RulesThe 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

NameDescriptionExample
limitRows per page (50 by default, at most 200)limit=100
offsetRows to skipoffset=200
qFree-text search over the search columnsq=acme
sortcolumn:asc or column:desc, several separated by commassort=created_at:desc
filterA JSON condition or group (see the filter language), URL-encoded; any field below can be filtered and sortedfilter={"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

NameTypeDescription
idstring (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.

FieldTypeRequiredDescription
codetextYesCode
nametextYesName
priorityintegerNoOrder — Every rule that matches applies; lower numbers collect their signatures first.
amount_thresholdnumericNoApplies 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_iduuidNoOnly for supplier
approver_kindtextNoWho 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)
levelsintegerNoLevels 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_roletextNoRole — 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_iduuidNoEmployee — 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_hoursintegerNoDue within (hours)
is_activebooleanNoActive
descriptiontextNoDescription
uses_levelsbooleanNoName 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_iduuidNoOnly 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_iduuidNoPerson — Anyone who signs in to this company. They decide it from My approvals, whatever modules they have.
approver_position_iduuidNoPosition — 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_iduuidNoPo 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

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Request body

Only the fields to change; fields left out keep their value.

FieldTypeRequiredDescription
codetextYesCode
nametextYesName
priorityintegerNoOrder — Every rule that matches applies; lower numbers collect their signatures first.
amount_thresholdnumericNoApplies 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_iduuidNoOnly for supplier
approver_kindtextNoWho 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)
levelsintegerNoLevels 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_roletextNoRole — 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_iduuidNoEmployee — 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_hoursintegerNoDue within (hours)
is_activebooleanNoActive
descriptiontextNoDescription
uses_levelsbooleanNoName 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_iduuidNoOnly 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_iduuidNoPerson — Anyone who signs in to this company. They decide it from My approvals, whatever modules they have.
approver_position_iduuidNoPosition — 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_iduuidNoPo 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

NameTypeDescription
idstring (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

NameTypeDescription
idstring (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

NameTypeDescription
idstring (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, withLines

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/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

NameTypeDescription
parentIdstring (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

NameTypeDescription
parentIdstring (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

NameTypeDescription
parentIdstring (uuid)The record's parentId, as a list returns it.
lineIdstring (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

NameTypeDescription
parentIdstring (uuid)The record's parentId, as a list returns it.
lineIdstring (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.

FieldTypeAccessDescription
iduuidread onlyId
org_iduuidread onlyOrg id
org_unit_iduuidread onlyOrganizational 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.
codetextread, writeCode
nametextread, writeName
priorityintegerread, writeOrder — Every rule that matches applies; lower numbers collect their signatures first.
amount_thresholdnumericread, writeApplies 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_iduuidread, writeOnly for supplier
approver_kindtextread, writeWho 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)
levelsintegerread, writeLevels 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_roletextread, writeRole — 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_iduuidread, writeEmployee — 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_hoursintegerread, writeDue within (hours)
is_activebooleanread, writeActive
descriptiontextread, writeDescription
created_attimestamp with time zoneread onlyCreated at
uses_levelsbooleanread, writeName 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_1textread onlyXf text 1
xf_text_2textread onlyXf text 2
xf_text_3textread onlyXf text 3
xf_text_4textread onlyXf text 4
xf_text_5textread onlyXf text 5
xf_num_1numericread onlyXf num 1
xf_num_2numericread onlyXf num 2
xf_num_3numericread onlyXf num 3
xf_date_1dateread onlyXf date 1
xf_date_2dateread onlyXf date 2
created_byuuidread onlyCreated by
updated_attimestamp with time zoneread onlyUpdated at
updated_byuuidread onlyUpdated by
cost_center_iduuidread, writeOnly 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_iduuidread, writePerson — Anyone who signs in to this company. They decide it from My approvals, whatever modules they have.
approver_position_iduuidread, writePosition — 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_iduuidread, writePo type id

Errors

StatusMeaning
400The request could not be read: a filter that is not JSON, a bad parameter
401No credential, or it is wrong, revoked or expired
403The caller's roles do not hold Supply Chain › PO Approval Rules for this verb, or the address or origin is not allowed
404No record with that id is visible to the caller
409A conflict: a duplicate number, a document in a state that does not allow it, or a record changed or locked by someone else
422Refused 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.