Skip to content

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.

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:

Terminal window
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" } ] }

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.

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.

  • 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 is 429 with Retry-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.

GET /reconciliation/processes?page=0&size=50

Terminal window
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 } }

GET /reconciliation/processes/{processId} — its set-up too: sides and their data sources (definition.sides, or dataSources for two-sided ones), matching, controls.

POST /reconciliation/processes/{processId}/run — reads each side’s data source (web links and connected systems are fetched again first). Needs the Member role.

Terminal window
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" } }

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.

Terminal window
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.

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.

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.

GET /reconciliation/processes/{processId}/runs?page=0&size=20 — newest first, each as above.

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.

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" } ] } }

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.

Large files are prepared in the background:

  1. POST /downloads with { "runId": "…", "format": "csv" } (or "xlsx") answers 202 with the download and its status: QUEUED, RUNNING, then READY (or FAILED). The same records asked again share one file.
  2. Poll GET /downloads/{id} until READY.
  3. GET /downloads/{id}/file returns 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.

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

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

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__.

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.

Terminal window
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"

GET /data-sources/{id}/records?page=0&size=100&search= — the rows of its newest copy.

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.

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.

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" } }

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.