TRANXACT.AI Help

Supply Chain · Procurement Control

Requisition Approval Rules

Which purchase requisitions need a signature, and whose. The same shape a purchase order rule has, because a company should express its delegation of authority once.

Type REST8 operationsBase path /api/scm/pr-approval-rulesPublished as /api/v1/pr-approval-rules

Download specification (OpenAPI 3.1) Screen: Requisition 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 › Requisition 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.pr_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

8 operations. Open one for its parameters, bodies, responses and a sample request.

GET/api/scm/pr-approval-rulesList requisition 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",
      "category": "text",
      "department": "text",
      "req_type": "standard",
      "item_type": "text",
      "warehouse_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
      "account_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
      "requires_subcontract": true,
      "approver_kind": "A named person (their sign-in) — no HRMS needed"
    }
  ],
  "count": 1
}

Sample request

curl "https://demo.tranxact.ai/api/scm/pr-approval-rules?limit=20" \
  -H "Authorization: Bearer $TOKEN"
GET/api/scm/pr-approval-rules/{id}Read one requisition 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",
  "category": "text",
  "department": "text",
  "req_type": "standard",
  "item_type": "text",
  "warehouse_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "account_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "requires_subcontract": true,
  "approver_kind": "A named person (their sign-in) — no HRMS needed"
}

404 when no record with that id is visible to the caller.

Sample request

curl "https://demo.tranxact.ai/api/scm/pr-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
  -H "Authorization: Bearer $TOKEN"
POST/api/scm/pr-approval-rulesCreate a requisition approval rule

Request body

The record as JSON. Fields marked Yes are required.

FieldTypeRequiredDescription
codetextYesCode
nametextYesRule
priorityintegerNoOrder — Lower runs first. Every matching rule applies; their signatures are collected in this order.
amount_thresholdnumericNoApplies at or above (inclusive) — A requisition no rule covers is released without approval: "Amounts covered" shows any gap.
categorytextNoOnly this category
departmenttextNoOnly this department
req_typetextNoOnly this kind of requisition
Allowed: standard subcontract service replacement rework
item_typetextNoItem type
warehouse_iduuidNoOnly this warehouse
account_iduuidNoOnly for this customer
requires_subcontractbooleanNoOnly subcontracting requisitions
approver_kindtextNoWho signs — Choose one; only the field for that choice is needed. The conditions above are all optional. "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)
levelsintegerNoHow many levels up
approver_roletextNoRole that may sign — The role’s NAME as it appears in Access › Roles — “Plant Manager”, not a slug. A rule naming a role nobody holds routes a requisition to nobody.
approver_employee_iduuidNoEmployee
due_in_hoursintegerNoDue within (hours)
is_activebooleanNoActive
descriptiontextNoWhy this rule exists
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.
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.
cost_center_iduuidNoOnly for cost center — Requisitions charged to this cost center, on the requisition or on any line. Leave empty for every cost center.

Sample body

{
  "code": "COD-000001",
  "name": "Example",
  "priority": 10,
  "amount_threshold": "1250.00",
  "category": "text",
  "department": "text"
}

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",
  "category": "text",
  "department": "text",
  "req_type": "standard",
  "item_type": "text",
  "warehouse_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "account_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "requires_subcontract": true,
  "approver_kind": "A named person (their sign-in) — no HRMS needed"
}

Sample request

curl -X POST "https://demo.tranxact.ai/api/scm/pr-approval-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"COD-000001","name":"Example","priority":10,"amount_threshold":"1250.00","category":"text","department":"text"}'
PUT/api/scm/pr-approval-rules/{id}Change a requisition 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
nametextYesRule
priorityintegerNoOrder — Lower runs first. Every matching rule applies; their signatures are collected in this order.
amount_thresholdnumericNoApplies at or above (inclusive) — A requisition no rule covers is released without approval: "Amounts covered" shows any gap.
categorytextNoOnly this category
departmenttextNoOnly this department
req_typetextNoOnly this kind of requisition
Allowed: standard subcontract service replacement rework
item_typetextNoItem type
warehouse_iduuidNoOnly this warehouse
account_iduuidNoOnly for this customer
requires_subcontractbooleanNoOnly subcontracting requisitions
approver_kindtextNoWho signs — Choose one; only the field for that choice is needed. The conditions above are all optional. "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)
levelsintegerNoHow many levels up
approver_roletextNoRole that may sign — The role’s NAME as it appears in Access › Roles — “Plant Manager”, not a slug. A rule naming a role nobody holds routes a requisition to nobody.
approver_employee_iduuidNoEmployee
due_in_hoursintegerNoDue within (hours)
is_activebooleanNoActive
descriptiontextNoWhy this rule exists
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.
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.
cost_center_iduuidNoOnly for cost center — Requisitions charged to this cost center, on the requisition or on any line. Leave empty for every cost center.

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",
  "category": "text",
  "department": "text",
  "req_type": "standard",
  "item_type": "text",
  "warehouse_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "account_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "requires_subcontract": true,
  "approver_kind": "A named person (their sign-in) — no HRMS needed"
}

Sample request

curl -X PUT "https://demo.tranxact.ai/api/scm/pr-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/pr-approval-rules/{id}Delete a requisition 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/pr-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
  -H "Authorization: Bearer $TOKEN"
POST/api/scm/pr-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/pr-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/pr-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/pr-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/level-history" \
  -H "Authorization: Bearer $TOKEN"
POST/api/scm/pr-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/pr-approval-rules/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"overrides":"value","preview":"value","withLines":"value"}'

Data model

Every field of a requisition 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 onlyOrg unit id
codetextread, writeCode
nametextread, writeRule
priorityintegerread, writeOrder — Lower runs first. Every matching rule applies; their signatures are collected in this order.
amount_thresholdnumericread, writeApplies at or above (inclusive) — A requisition no rule covers is released without approval: "Amounts covered" shows any gap.
categorytextread, writeOnly this category
departmenttextread, writeOnly this department
req_typetextread, writeOnly this kind of requisition
Allowed: standard subcontract service replacement rework
item_typetextread, writeItem type
warehouse_iduuidread, writeOnly this warehouse
account_iduuidread, writeOnly for this customer
requires_subcontractbooleanread, writeOnly subcontracting requisitions
approver_kindtextread, writeWho signs — Choose one; only the field for that choice is needed. The conditions above are all optional. "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, writeHow many levels up
approver_roletextread, writeRole that may sign — The role’s NAME as it appears in Access › Roles — “Plant Manager”, not a slug. A rule naming a role nobody holds routes a requisition to nobody.
approver_employee_iduuidread, writeEmployee
due_in_hoursintegerread, writeDue within (hours)
is_activebooleanread, writeActive
descriptiontextread, writeWhy this rule exists
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
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.
cost_center_iduuidread, writeOnly for cost center — Requisitions charged to this cost center, on the requisition or on any line. Leave empty for every cost center.

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 › Requisition 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.