Connecting other software to TRANXACT: the published API
Every TRANXACT installation answers other software at <your TRANXACT address>/api/v1, with an API key issued under Platform › Published API. Only what an administrator has published and granted can be reached, as a named user of the company, through the same rules and audit trail as the screen.
The address
The published API lives at /api/v1 on the same address people sign in at. The address differs per installation; the path does not.
| Installation | API pubblicata |
|---|---|
| Your company’s own address | <your TRANXACT address>/api/v1 |
| US demonstration | https://demo.tranxact.ai/api/v1 |
| India demonstration | https://indemo.tranxact.ai/api/v1 |
| Saudi Arabia demonstration | https://ksademo.tranxact.ai/api/v1 |
| A company on a shared (multi-tenant) installation | the address that company signs in at, followed by /api/v1 |
| A private installation | its own address, followed by /api/v1 |
Everything below uses the US demonstration address as an example. Replace it with your own. Why each setting exists, and the roles that keep publishing and issuing keys apart, are in Letting other software read your data.
Before the first call: what an administrator sets up
- Publish what may leave the company: Platform › Published API › Exposures. One exposure is one screen, published under a name of your choosing (Published as), with the columns that may travel (every column, every column but some, or only the ones named), the rows that may travel (Rows that may travel, a filter), the most rows per call, and whether it May be read, created, changed or deleted. Nothing is reachable until it is published here.
- Register the software: Platform › Published API › API Clients. Say what it is, who to ask about it, its Protocol (REST, MCP or both) and who it Acts as — a named user of this company. Every call runs as that user, so a key can never reach anything that user could not.
- Issue the key: the Issue key action on the client. The key is shown once; store it. Issuing a new one stops the old one at once. A key starts with tx_ and the client’s code, so a leaked one is recognisable.
- Grant the client what it may use: Platform › Published API › API Grants, one row per exposure, with May read / create / change / delete and an optional expiry. A grant can only narrow what the exposure allows.
- Say where the key may be used from: Platform › Published API › Allowed Software — a browser origin, a host, an address or an IPv4 network (CIDR). A client is created with Only from allowed addresses ticked, and a key that requires an allowlist and has none reaches nothing.
- Watch it: Platform › Published API › API Call Log lists every call, allowed or refused, with the reason for each refusal; API Studio is the board over all of it.
Authenticating
Send the key on every call, as a bearer token or, for software that can only send a fixed header, as X-API-Key.
curl https://demo.tranxact.ai/api/v1 \
-H "Authorization: Bearer tx_partner_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# the same, for software that cannot send Authorization
curl https://demo.tranxact.ai/api/v1 -H "X-API-Key: tx_partner_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET /api/v1 answers whether the key works at all: which client it is, who it acts as, how many resources it may reach, and where the catalogue, the OpenAPI document and the MCP endpoint are. Without a key the answer is 401 and says how to send one.
What this key may reach
- GET /api/v1/resources — every exposure granted to this key: its code, name, path (/api/v1/<code>), the columns it carries, the most rows per call, and which of read, create, change and delete it may do.
- GET /api/v1/openapi.json — the same as an OpenAPI 3.1 document, generated from this key’s own grants. It lists exactly the paths that work for this key and no others, so it can be loaded straight into Postman, Swagger UI or a code generator.
Reading, creating, changing and deleting
| Chiamata | Cosa fa | Risposta |
|---|---|---|
| GET /api/v1/<code> | A list | { rows, count, limit, offset }, and the total in the X-Total-Count header |
| GET /api/v1/<code>/<id> | One record | The record, or 404 when no such record is published |
| POST /api/v1/<code> | Creare | 201 and the record as created |
| PATCH or PUT /api/v1/<code>/<id> | Modifica | The changed record |
| DELETE /api/v1/<code>/<id> | Eliminare | What the screen answers for a deletion |
# the first 50 published invoices (the exposure was published as "invoices")
curl "https://demo.tranxact.ai/api/v1/invoices?limit=50" -H "Authorization: Bearer $KEY"
# search, sort and page
curl "https://demo.tranxact.ai/api/v1/invoices?q=steel&sort=invoice_date:desc&limit=20&offset=40" -H "Authorization: Bearer $KEY"
# a filter: posted, and at least 1000
curl -G "https://demo.tranxact.ai/api/v1/invoices" -H "Authorization: Bearer $KEY" \
--data-urlencode 'filter={"join":"and","conditions":[{"col":"status","op":"eq","value":"posted"},{"col":"total","op":"gte","value":1000}]}'
# one record
curl "https://demo.tranxact.ai/api/v1/invoices/7c0e…" -H "Authorization: Bearer $KEY"
# create, and change
curl -X POST "https://demo.tranxact.ai/api/v1/leads" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"company_name":"Example Traders","email":"buyer@example.com"}'
curl -X PATCH "https://demo.tranxact.ai/api/v1/leads/5b1f…" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"status":"qualified"}'
- limit is 50 when not given, and never more than the exposure’s Most rows per call; offset pages through.
- q searches the screen’s own search columns; sort is column:asc or column:desc.
- filter is JSON: one condition { "col", "op", "value" } (or "values" for a list), or a group { "join": "and" | "or", "conditions": [ … ] }. The operators are eq, ne, in, not_in, contains, starts, gt, gte, lt, lte, between, not_between, on, before, after, last_days, not_last_days, empty and not_empty. Your filter is always applied underneath the exposure’s own Rows that may travel, so nothing you send can widen what was published.
- A field the exposure did not publish is left out of every answer, and is not written when you send it.
- A by-id call reads through the same published row filter, so a record outside it is 404 whether you read, change or delete it.
What happens to a call
A published call is not a back door. After the key, the client, the address and the rate are checked, it becomes an ordinary call to the same route the screen uses, made as the client’s Acts as user. The company and business-unit scope, period locks, posting rules, numbering, validation, custom fields, custom logic and approvals all apply, and the record’s own audit trail records the change as made through the API.
Limits and refusals
| Risposta | Perché |
|---|---|
| 401 | No key was sent, or the key is not recognised (a revoked key reads the same). |
| 403 | The key is suspended or expired; it is presented from an address not on Allowed Software; it is a REST key at the MCP endpoint or the reverse; or the exposure does not allow that verb. |
| 404 | Nothing is published under that code for this key, or no published record has that id. |
| 400 / 422 | The filter is not JSON, or the record was refused by the screen’s own rules (the error says which). |
| 429 | More calls this minute than the client’s Rate limit per minute (120 unless changed), with Retry-After; or too many calls from one address without a valid key. |
| 503 | The client’s Acts as user is inactive or belongs to another company, so there is nobody to act as. |
Every answer that is not a success is JSON with an error sentence. Every call, allowed or refused, is on the API Call Log.
From a browser
A web page on another site may call the published API only from an origin named on Allowed Software. A preflight from an allowed origin is answered; the real request is then checked in full against the key it carries.
Software that needs more than the published API
An integration that must work like a person across whole modules — a data load, a support desk, a nightly job — can instead use a service account (Platform › Access › Service Accounts). It holds roles like a person, cannot sign in to the console, and exchanges its secret, shown once, for a short-lived token at POST /api/auth/service-token. That token is sent as a bearer token to the same /api/<module>/<screen> routes the console uses, with that account’s roles deciding what it may do. Prefer the published API wherever it is enough: it is narrower, per partner, and logged per call.
curl -X POST https://demo.tranxact.ai/api/auth/service-token -H "Content-Type: application/json" \
-d '{"client_id":"loader@service.example","secret":"<the secret>"}'
# → { "token": "…", "token_type": "Bearer", "expires_in": 3600, … }
curl "https://demo.tranxact.ai/api/crm/accounts?limit=20" -H "Authorization: Bearer <token>"
Every endpoint, verb, parameter and field: API endpoint reference: how to call TRANXACT, with a page per module and the full OpenAPI file. See also TRANXACT as an MCP server, and Which screen connects what for the difference between software reaching TRANXACT and TRANXACT reaching other software.