One login per caller
Sign in with POST /api/authenticate and send the token as Authorization: Bearer. An admin sets up agent logins and chooses what each may reach.
PUBLIC API REFERENCE · VERSION 1.0
35 routes we keep stable for your systems and agents.
Sign in, send in data, run plans, read pay and its trace, follow approvals and disputes, run reports. Every call keeps the login’s rights, organization, reach and pay rule, the same as the screens.
THE RULES
What every call keeps.
Same rights as the screens
Rows outside the login’s organization and reach are not there; pay amounts follow the pay rule. Missing and not-allowed records give the same answer.
Agents prepare, people decide
An agent login may read, check and load data, and ask for runs. Approving, rejecting and sending back are for people only; a held load or a full run waits for a person.
A promise, kept
These routes change only with notice and a new version. Other routes the screens use may change without notice; build on these.
Safe retries and fair limits
Send an Idempotency-Key header on writes to make retries safe. Rate limits and daily write budgets apply to agent logins.
Sandbox
PlannedSandbox credentials for evaluation are planned. Today we set up a scoped evaluation login on request.
THE ROUTES
35 routes in 8 groups.
Paths are relative to https://revexcommissions.com. The OpenAPI file has every parameter and request field.
Sign in
Every call carries the token of one login: a person's, or an agent login an admin set up.
| Route | What it does | Who may call it | Agent login |
|---|---|---|---|
| POST /api/authenticate | Signs in: { email, password }; answers with id_token, the bearer token for every other call | Any login (a person's or an agent login's) | May call |
| GET /api/account | Who the token belongs to: login, organization, roles and language | Any signed-in login | May call |
Example: Sign in, then ask who the token belongs to
curl -s -X POST https://revexcommissions.com/api/authenticate \
-H "Content-Type: application/json" \
-d '{"email": "erp-agent@yourco.com", "password": "..."}'
curl -s https://revexcommissions.com/api/account -H "Authorization: Bearer $TOKEN"{ "id_token": "eyJhbGciOi..." }Send in data
Check a file against the published format, look at what would load, then load it.
| Route | What it does | Who may call it | Agent login |
|---|---|---|---|
| GET /api/uploads/catalogue | The catalogue: the organization's settings, then each group's objects with what the organization chose | Upload or sales-load right | May call |
| GET /api/uploads/objects/{code}/formats | An object's format versions, newest first | Upload or sales-load right | May call |
| POST /api/uploads/objects/{code}/check | Checks a file with the object's published format: { file, fingerprint, size, headers, rows, controlTotals? } | Upload right (master data) or sales-load right (sales) | May call |
| GET /api/uploads/engine/batches/{id} | One upload with its counts, holds and the rows that need a look | Upload or sales-load right | May call |
| POST /api/uploads/engine/batches/{id}/load | Loads a checked upload; one that is held goes for approval instead (it loads when approved) | Upload or sales-load right; a held batch waits for a person's approval | May call |
Example: Check a file of invoice lines, then load it
curl -s -X POST https://revexcommissions.com/api/uploads/objects/INVOICE_LINES/check \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"file": "invoices_2026-10.csv", "size": 18234, "fingerprint": "9f2c...",
"headers": ["Invoice No", "Line No", "Invoice Date", "Sold To", "Product", "Quantity", "Line Amount"],
"rows": [{"Invoice No": "INV-1001", "Line No": 1, "Invoice Date": "2026-10-06",
"Sold To": "C-100245", "Product": "P-7781", "Quantity": 10, "Line Amount": 1000}]}'
curl -s -X POST https://revexcommissions.com/api/uploads/engine/batches/4812/load -H "Authorization: Bearer $TOKEN"{ "id": 4812, "status": "CHECKED", "total": 1, "holdReasons": [], "rows": [ ... ] }
{ "id": 4812, "status": "LOADED", "loaded": 1, ... } or, when held: { "status": "WAITING_APPROVAL", ... }Plans
Read plans, their versions, periods and results.
| Route | What it does | Who may call it | Agent login |
|---|---|---|---|
| GET /api/plan-engine/plans | The organization's plans and their versions | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/plans/{code}/versions/{no}/document | A version as the document it was saved from (codes, not IDs) — what the plan builder edits | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/plans/{code}/versions/{no}/periods | The pay periods a version runs in, with what the latest run of each did | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/plans/{code}/versions/{no}/results | Per seat results of a pay period (latest runs): holder, attainment, amount by block, total | The rights of the login; rows inside its reach; pay by the pay rule | May call |
Example: Read a plan version and its periods
curl -s https://revexcommissions.com/api/plan-engine/plans -H "Authorization: Bearer $TOKEN" curl -s https://revexcommissions.com/api/plan-engine/plans/SALES-2027/versions/1/periods -H "Authorization: Bearer $TOKEN"
Runs
Ask for a calculation run, follow it, and read its breakdown and proof.
| Route | What it does | Who may call it | Agent login |
|---|---|---|---|
| POST /api/plan-engine/plans/{code}/versions/{no}/runs | Runs a compiled version for a pay period: { "period": "FY2027-Q1", "runType": "TEST" | "FULL", "scope": "ALL" | "CHANGED | Run right; a full run posts only after a person approves it | May call |
| GET /api/plan-engine/run-requests/{id} | A queued run: status (QUEUED, RUNNING, DONE, FAILED), origin, cause, job, and its result or error | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/monitor/runs | All calculation runs (newest first, up to 500), with optional filters: plan, period, status, type, who, from, to (dates) | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/monitor/runs/{runId}/breakdown | One run broken down: by EMPLOYEE, TEAM, TERRITORY (level: roll up to that hierarchy level) or RULE; filterBy (TEAM, TERR | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/monitor/runs/{runId}/proof | A run's proof: every sale accounted for, lines = seats = blocks = total, each rate line's arithmetic re-done, payees, ro | The rights of the login; rows inside its reach; pay by the pay rule | May call |
Example: Ask for a test run and follow it
curl -s -X POST https://revexcommissions.com/api/plan-engine/plans/SALES-2027/versions/1/runs \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"period": "FY2027-Q1", "runType": "TEST", "wait": false}'
curl -s https://revexcommissions.com/api/plan-engine/run-requests/9021 -H "Authorization: Bearer $TOKEN"{ "requestId": 9021, ... }
{ "status": "DONE", "runId": 3307, ... } (QUEUED, RUNNING, DONE or FAILED)Payees and pay
Payees, statements, payment runs, and the trace from a payment back to the sales.
| Route | What it does | Who may call it | Agent login |
|---|---|---|---|
| GET /api/plan-engine/payees | The payee listing | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/payees/{partnerId} | One payee's register | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/payees/{partnerId}/statements | Statement level 1: every pay run that paid the payee | The payee, their manager, pay roles | May call |
| GET /api/plan-engine/payees/{partnerId}/statements/{lineId}/lines | Statement level 3: the transactions behind a payment (optionally one component), paged (limit up to 1,000) | The payee, their manager, pay roles | May call |
| GET /api/plan-engine/payments/runs | The organization's payment runs, newest first | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/payments/runs/{id} | One payment run with its lines, holds and checks | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/plan-engine/payments/runs/{id}/lines/{lineId}/trace | The ledger lines one payment line pays (plan, period, seat, kind, amount) | The rights of the login; rows inside its reach; pay by the pay rule | May call |
Example: From a payment line back to what it pays
curl -s https://revexcommissions.com/api/plan-engine/payments/runs -H "Authorization: Bearer $TOKEN" curl -s https://revexcommissions.com/api/plan-engine/payments/runs/118/lines/5530/trace -H "Authorization: Bearer $TOKEN"
Approvals
What waits for whom. Deciding is for people: an agent login never approves.
| Route | What it does | Who may call it | Agent login |
|---|---|---|---|
| GET /api/approvals | The organization's items: PENDING by default; ?status=APPROVED, REJECTED, SUPERSEDED, or ALL (latest 200) | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/approvals/{id}/trail | The workflow trail of an item: steps done with who, when and how they were found, the open step and its holders, the ste | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| POST /api/approvals/{id}/approve | An approver on the open step approves the item: { note, approvalMode } | The people asked at the open step (a person; never an agent login) | People only |
| POST /api/approvals/{id}/reject | An approver on the open step rejects the item: { note } | The people asked at the open step (a person; never an agent login) | People only |
| POST /api/approvals/{id}/send-back | An approver on the open step sends the item back to the person who asked, saying what must change | The people asked at the open step (a person; never an agent login) | People only |
Example: What waits, and an item's trail
curl -s https://revexcommissions.com/api/approvals -H "Authorization: Bearer $TOKEN"
curl -s https://revexcommissions.com/api/approvals/7710/trail -H "Authorization: Bearer $TOKEN"
# a person decides (an agent login gets 403):
curl -s -X POST https://revexcommissions.com/api/approvals/7710/approve \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"note": "Checked against the deal desk"}'Disputes
Read disputes and raise one. An agent login's dispute stays a draft for a person to send.
| Route | What it does | Who may call it | Agent login |
|---|---|---|---|
| GET /api/v1/disputes | Disputes: scope MINE (raised by me / about me), TEAM (managers: their team), QUEUE (the teams: all); filters status (com | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/v1/disputes/{id} | One dispute with its timeline, attachments and what the caller may do next | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| POST /api/v1/disputes | Raises a dispute: { type, title, description, amountClaimed, currency, payeePartnerId (on behalf), planVersionId, period | The payee, or a role that raises disputes for others | May call |
| POST /api/v1/disputes/{id}/messages | A message on the dispute (payee side or team; team notes may be internal) | People on the dispute (a person) | People only |
Example: Raise a dispute about a payment line
curl -s -X POST https://revexcommissions.com/api/v1/disputes \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"type": "MISSING_CREDIT", "title": "October invoice INV-1001 not credited",
"description": "Sold to C-100245 on 6 Oct", "paymentLineId": 5530}'Reports
The reports a login may open, their inputs, and their rows.
| Route | What it does | Who may call it | Agent login |
|---|---|---|---|
| GET /api/reports | The report areas and the reports the caller may open, in order | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| GET /api/reports/{code} | One report's inputs, columns and default view (charts, grouping, pivot) | The rights of the login; rows inside its reach; pay by the pay rule | May call |
| POST /api/reports/{code}/run | Runs a report with the inputs given (only the report's own inputs are read) inside the caller's reach | The rights of the login; rows inside its reach; pay by the pay rule | May call |
Example: Run a report with its inputs
curl -s https://revexcommissions.com/api/reports/A1 -H "Authorization: Bearer $TOKEN"
curl -s -X POST https://revexcommissions.com/api/reports/A1/run \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"inputs": {"from": "2026-04-01", "to": "2026-06-30"}}'{ "rows": [ { "division": "...", "status": "...", ... } ] }REQUEST AN API ROUTE
Need something these routes do not cover?
Tell us what your system or agent needs to do. We review each request: if it fits, it joins the published list with a worked example and a new version of the OpenAPI file; if not, we suggest the routes that already do the job.
01
What it should do
Read or send which data, for which job.
02
Who calls it
A system, an agent or a person, and how often.
03
What you use today
Any route you call now, or a file you send.
API ROUTE REQUEST