API reference
This is the reference for the API: how to authenticate, then each request with what it takes and what it gives back. Start with the API if you have not created a key yet.
Basics
Section titled “Basics”| Base URL | https://api.refinepoint.com |
| Authentication | the key in the X-API-Key header. Send either a key or a bearer token, never both (400). |
| Workspace | every path starts with /api/v1/organizations/{code}, where {code} is the workspace’s code (Settings → Organization). A key belongs to one workspace; any other code answers 403. |
| Format | JSON in and out (Content-Type: application/json), except file uploads (multipart/form-data) and downloads. |
| Ids | UUIDs, such as 0d6c3a1e-6f0b-4c4e-9d0e-2f9a6c1b7e55. Dates and times are ISO 8601. |
Which workspace a key belongs to:
curl https://api.refinepoint.com/api/v1/organizations/me -H "X-API-Key: $RP_KEY"{ "success": true, "data": [ { "id": "…", "shortCode": "acme-finance", "displayName": "Acme Finance", "kind": "TEAM", "role": "MEMBER" } ] }What a key can reach
Section titled “What a key can reach”A key can call every workspace request its role allows (Viewer, Member or Admin, the same as a person with that role), except:
- members, API keys and billing (
/members,/api-keys,/billing), so a leaked key cannot grant itself more; - exporting the workspace (
/export), which is for its owner in person; - the workspace profile itself, and anything outside
/api/v1/organizations/{code}/….
Those answer 403. The requests below are the ones systems use most; the rest of the workspace’s requests work the same
way.
Answers and errors
Section titled “Answers and errors”Every answer has the same envelope:
{ "success": true, "data": { }, "message": "Run started", "errors": [], "meta": { "timestamp": "2026-10-25T07:41:52Z", "requestId": "1c26502e-…" } }| Status | Means | What to do |
|---|---|---|
200, 201, 202 |
Done (201 created, 202 accepted and carrying on in the background) |
Read data |
400 |
Something sent is wrong; message says what |
Fix the request |
401 |
No key, or the key is invalid, revoked or expired | Use a valid key |
402 |
The workspace’s plan does not include it, or a limit is reached | Upgrade, or remove something |
403 |
The key’s role does not allow it, or keys cannot use this request | Use a key with a higher role, or do it in the app |
404 |
Not found in this workspace | Check the id |
409 |
It conflicts with the current state (two changes at once) | Read again, then retry |
429 |
Too many requests in the last minute | Wait the seconds in Retry-After, then retry |
5xx |
Something went wrong at RefinePoint | Retry later; quote meta.requestId to support |
When success is false, message says why in plain words and errors may list each problem.
The same requests are described in OpenAPI 3.1, one document per area, at
api.refinepoint.com/api/docs to read and try out, and as JSON at
https://api.refinepoint.com/api/v1/public/openapi (the list of areas) for generating a client.
Limits
Section titled “Limits”- Each API key may make 300 requests a minute, and each address 1,800. Every answer says how many are left in
X-RateLimit-Remaining; past the limit the answer is429withRetry-After(seconds). - Refreshing a data source from its link or connected system counts against the plan’s refreshes a day, the same as Refresh now in the app, and a data source is fetched at most once a minute.
- Files are up to 50 MB each.
Reconciliations
Section titled “Reconciliations”List reconciliations
Section titled “List reconciliations”GET /reconciliation/processes?page=0&size=50
curl "https://api.refinepoint.com/api/v1/organizations/acme-finance/reconciliation/processes?size=50" -H "X-API-Key: $RP_KEY"{ "success": true, "data": { "content": [ { "id": "9b2…", "name": "HDFC current account", "typeCode": "CASH", "status": "ACTIVE", "totalRuns": 42, "lastRunAt": "2026-10-25T07:05:00", "version": 4 } ], "page": 0, "size": 50, "totalElements": 1, "totalPages": 1 } }One reconciliation
Section titled “One reconciliation”GET /reconciliation/processes/{processId} — its set-up too: sides and their data sources (definition.sides, or
dataSources for two-sided ones), matching, controls.
Start a run
Section titled “Start a run”POST /reconciliation/processes/{processId}/run — reads each side’s data source (web links and connected systems are
fetched again first). Needs the Member role.
curl -X POST https://api.refinepoint.com/api/v1/organizations/acme-finance/reconciliation/processes/9b2…/run -H "X-API-Key: $RP_KEY"{ "success": true, "message": "Run started", "data": { "id": "0044d9fe-…", "processId": "9b2…", "runNumber": 43, "status": "RUNNING", "startedAt": "2026-10-25T08:00:00" } }Start a run with files for that run only
Section titled “Start a run with files for that run only”POST /reconciliation/processes/{processId}/run/files — multipart, one file per side, each part named by the side’s
code (SOURCE and TARGET for two-sided reconciliations, or the codes in definition.sides). The run reads the files
in place of the data sources, which stay as they are; sides without a file read their data source.
curl -X POST https://api.refinepoint.com/api/v1/organizations/acme-finance/reconciliation/processes/9b2…/run/files \ -H "X-API-Key: $RP_KEY" -F "SOURCE=@ledger-october.csv"An unknown side code answers 400.
Run again on an earlier run’s data
Section titled “Run again on an earlier run’s data”POST /reconciliation/processes/{processId}/runs/{runId}/rerun — the same data each side of that run read, with
today’s rules. Useful to see what a rule change does to a past period.
Check a run
Section titled “Check a run”GET /reconciliation/runs/{runId} — poll until status is COMPLETED or FAILED (every 5–10 seconds is plenty).
{ "success": true, "data": { "id": "0044d9fe-…", "runNumber": 43, "status": "COMPLETED", "startedAt": "2026-10-25T08:00:00", "completedAt": "2026-10-25T08:00:07", "sourceCount": 1869, "targetCount": 1854, "matchedCount": 1802, "partialCount": 41, "unmatchedCount": 26, "matchRate": 96.4, "totalVariance": 1018.00, "errorMessage": null, "processVersion": 4 } }A failed run has status: "FAILED" and errorMessage saying why.
List a reconciliation’s runs
Section titled “List a reconciliation’s runs”GET /reconciliation/processes/{processId}/runs?page=0&size=20 — newest first, each as above.
Read a run’s results
Section titled “Read a run’s results”GET /reconciliation/processes/{processId}/runs/{runId}/results
| Parameter | |
|---|---|
status |
MATCHED, PARTIAL, UNMATCHED, DUPLICATE or EXCEPTION; all when left out |
search |
text found in any column |
page, size |
from 0; size up to 500 (100 when left out) |
pageBy |
_match_key to page by whole matches, so a matched pair is never split across pages |
{ "success": true, "data": { "columns": ["_match_key", "_side", "_match_status", "_break_cause", "reference", "date", "amount"], "rows": [ { "_match_key": "A4EB85C6", "_side": "SOURCE", "_match_status": "UNMATCHED", "_break_cause": "No matching target record for key: inv 0019", "reference": "INV-0019", "date": "2026-10-03", "amount": 250.00 } ], "totalRows": 26, "page": 0, "size": 100 } }Columns starting with _ are RefinePoint’s; the rest are the reconciliation’s fields.
What changed since the run before
Section titled “What changed since the run before”GET /reconciliation/processes/{processId}/runs/{runId}/changes — breaks new in this run, cleared since the run
before, still open, and records added or removed on each side.
{ "success": true, "data": { "available": true, "runNumber": 43, "previousRunNumber": 42, "newBreaks": 3, "cleared": 5, "stillOpen": 21, "added": 64, "removed": 0, "sides": [ { "side": "SOURCE", "added": 34, "removed": 0 } ], "newSample": [ { "side": "SOURCE", "label": "INV-0412", "status": "UNMATCHED", "previousStatus": null, "cause": "No matching target record" } ] } }What each side of a run read
Section titled “What each side of a run read”GET /reconciliation/processes/{processId}/runs/{runId}/inputs — per side: its data source or the file given for the
run, rows and columns. GET …/inputs/{side}/rows downloads the rows it read (CSV, gzip); GET …/inputs/{side}/file
downloads a file given for the run as it was uploaded.
Download a run’s records
Section titled “Download a run’s records”Large files are prepared in the background:
POST /downloadswith{ "runId": "…", "format": "csv" }(or"xlsx") answers202with the download and itsstatus:QUEUED,RUNNING, thenREADY(orFAILED). The same records asked again share one file.- Poll
GET /downloads/{id}untilREADY. GET /downloads/{id}/filereturns the file.
{ "success": true, "data": { "id": "5e1…", "runId": "0044d9fe-…", "format": "csv", "status": "READY", "fileName": "HDFC current account - run 43.csv", "sizeBytes": 412880, "rowCount": 3723, "expiresAt": "2026-11-01T08:01:00Z" } }Ready files are kept for 7 days.
Breaks
Section titled “Breaks”List breaks
Section titled “List breaks”GET /reconciliation/records — the records of every reconciliation’s latest run, as on the Breaks page.
| Parameter | |
|---|---|
status |
one or more of UNMATCHED, PARTIAL, DUPLICATE, EXCEPTION, SUGGESTED, MATCHED, PASSED (repeat the parameter) |
processId, typeCode |
one reconciliation, or one type |
review |
OPEN or APPROVED |
state, label, reason, assignedTo |
the workflow state, a label, a reason code, a person (or none) |
search |
reference, party or reconciliation name |
page, size |
from 0; size up to 500 (50 when left out) |
{ "success": true, "data": { "content": [ { "processId": "9b2…", "processName": "HDFC current account", "runId": "0044d9fe-…", "runNumber": 43, "matchKey": "A4EB85C6", "status": "UNMATCHED", "breakCause": "No matching target record", "date": "2026-10-03", "reference": "INV-0019", "party": "Tata Steel", "sourceAmount": 250.00, "targetAmount": null, "difference": 250.00, "reviewStatus": "OPEN", "workflowState": "OPEN", "assignedTo": null, "labels": [] } ], "totalElements": 26, "summary": { "total": 26, "byStatus": { "UNMATCHED": 19, "PARTIAL": 7 }, "approved": 0, "totalDifference": 1018.00 } } }Act on breaks
Section titled “Act on breaks”Each takes items: [{ "processId": "…", "runId": "…", "matchKey": "…" }], and needs the role to resolve breaks.
| Request | Body |
|---|---|
POST /reconciliation/records/review |
items, decision (APPROVED or OPEN), comment |
POST /reconciliation/records/transition |
items, state (a workflow state’s code), comment |
PUT /reconciliation/records/assignment |
items, assignedTo (a person’s id, or null), dueAt |
Data sources
Section titled “Data sources”List data sources
Section titled “List data sources”GET /data-sources
{ "success": true, "data": [ { "id": "3f1…", "name": "Bank statement", "sourceType": "FILE", "status": "connected", "config": { "fileName": "hdfc-october.csv", "uploadedAt": "2026-10-24T18:02:11Z", "fields": [ { "name": "Amount", "type": "number" } ] } } ] }Secrets in config (passwords, keys, links) are never returned; they read __MASKED__.
Upload a new file
Section titled “Upload a new file”POST /data-sources/{id}/upload — multipart, field file. The file becomes the data source’s newest copy; bank
statements (MT940, CAMT.053, BAI2, OFX) and tax files are converted, and its data quality rules are applied.
curl -X POST https://api.refinepoint.com/api/v1/organizations/acme-finance/data-sources/3f1…/upload \ -H "X-API-Key: $RP_KEY" -F "file=@hdfc-october.csv"Read its records
Section titled “Read its records”GET /data-sources/{id}/records?page=0&size=100&search= — the rows of its newest copy.
Refresh it
Section titled “Refresh it”POST /data-sources/{id}/refresh — for a data source with a web link or a connected system: fetches it again through
the queue (answers 202). GET /data-sources/{id}/refresh gives the latest refresh: status QUEUED, RUNNING,
DONE (with changed: whether new data was stored) or FAILED (with error). Counts against the plan’s refreshes a day;
fetched less than a minute before, the answer has fresh: true and the earlier fetch.
File routing
Section titled “File routing”Send a file
Section titled “Send a file”POST /ingest/submissions — multipart, field file; optional processId and side to place it yourself. Your
routes decide where it goes and whether to run.
{ "success": true, "data": { "id": "c71…", "channel": "API", "fileName": "HDFC_20261022.csv", "status": "DELIVERED", "routeName": "HDFC statements", "processId": "9b2…", "sideCode": "SOURCE", "runId": null, "message": "Delivered to HDFC current account, Bank side" } }GET /ingest/submissions?status=&processId= lists what was sent, and where it went.
Lookup tables and rules
Section titled “Lookup tables and rules”| Request | |
|---|---|
GET /lookups |
the workspace’s lookup tables |
GET /lookups/{CODE}/rows |
a table’s rows |
POST /lookups/{CODE}/rows |
add a row: { "column": "value", … } |
POST /expressions/evaluate |
try a rule: { "expression": "the group of party in VENDORS", "variables": { "party": "Tata Steel" } } |
Notifications
Section titled “Notifications”GET /notifications/inbox lists the key’s creator’s unread notifications (a run finished, a download is ready); a
system can use it instead of polling runs.