REST API
On this page
- Enabling and disabling the API
- Managing API users
- Authenticating requests
- Rate limiting
- Response envelope
- Endpoints
- Examples
- Refuse a write when the record changed (ETag and If-Match)
- Values array — field names by data type
- Lookalikes in the answer
- Old codes of merged records
- Merge and unmerge records
- Reading every page
- Error codes
- Approval workflows and the API
- Usage tracking
- Database tables
- Authentication flow
- Related
- Further reading
The REST API lets external applications read and write entity records over HTTP. Access is controlled with API keys. Each key belongs to a service account — an API user — that takes part in the same role and permission system as a human user.

Or watch the whole life of a key — created and shown once, three real calls and their answers, a write refused by the account's own role, the old key answering 401 the moment it is regenerated, and every call answering 503 with the kill switch off:
The API is for server-to-server use only. No CORS headers are set, so browser calls from another origin are blocked. Call it from a backend service, a script, or an integration platform.
Enabling and disabling the API
The global kill switch is in Settings › General Settings › API.
- On (default) — valid API key requests are processed normally
- Off — every request using
X-API-Keyreturns503 Service Unavailable, whatever the key
The toggle saves immediately and takes effect at once. Use it to suspend all external access without deleting a key.
Managing API users
Go to Settings › Access Management › API Users.
Each API user is a dedicated identity for one integration. It is subject to the same roles and permissions as a regular user, so assign only the roles the integration needs.
A column that the API user's roles set to None is left out of every record and out of the entity's attribute list. A create or update that names such a column answers 403 PERMISSION_DENIED with the message No access to column "Salary"., and nothing is written. If the API user has another role that grants the column, it stays visible. See Roles & Permissions.
The How API users work panel at the top of that screen sets out the three steps and stays folded away once you have read it.
Notes
Every API user carries a note — 500 characters, counted down as you type. Use it for what the account is for, who runs it, and which system calls it. It is shown under the name in the list and survives regenerating the key, which is the moment you are most likely to want it.
Create an API user:
- Click New API user.
- Enter a display name. This field is required.
- Optionally name the key. A label helps when you manage several.
- Assign one or more roles.
- Optionally set a key expiry date. Leave it blank for a key that never expires.
- Click Save.
The key is shown once, immediately after creation. Copy it now — it cannot be retrieved again. Only a SHA-256 hash is stored.
Edit — click a row to change the display name, roles, active status or expiry. The key is not affected.
Regenerate key — the old key is invalidated at once, and any integration using it gets 401 Unauthorized on its next request. The new key is shown once.
Delete — removes the service account. Calls using its key return 401 immediately.
The list shows the key prefix, roles, status (Active, Inactive, Expired or No key), call count, last use and expiry. Every column header sorts.
Authenticating requests
Send the key in the X-API-Key header on every request:
The format is prm_ followed by a random string. Never send the key as a query parameter or in the body.
Rate limiting
The API accepts 300 requests per minute per key. Requests over the limit return 429 with error code RATE_LIMITED. Callers without a key are limited by client address instead.
Response envelope
Every endpoint is under /api/v1/ and returns the same shape:
Errors return:
Endpoints
Entities
| Method | Path | Description |
|---|---|---|
GET | /api/v1/entities | List the entities the API user can read |
GET | /api/v1/entities/:entityId | Entity metadata and attribute definitions |
Records
| Method | Path | Description |
|---|---|---|
GET | /api/v1/entities/:entityId/records | List records, paginated |
GET | /api/v1/entities/:entityId/records/:recordId | One record |
GET | /api/v1/entities/:entityId/records/by-code/:code | One record, found by its code |
POST | /api/v1/entities/:entityId/records | Create a record |
PUT | /api/v1/entities/:entityId/records/:recordId | Update a record |
DELETE | /api/v1/entities/:entityId/records/:recordId | Delete a record |
POST | /api/v1/entities/:entityId/lookalikes/search | Records that look like the values you send. Saves nothing |
Lookalikes: merge and unmerge
| Method | Path | Description |
|---|---|---|
GET | /api/v1/entities/:entityId/lookalikes/groups | Open groups of lookalikes, best score first, paginated |
POST | /api/v1/entities/:entityId/lookalikes/merge | Merge records into one, by code |
GET | /api/v1/entities/:entityId/lookalikes/merges | Merges of the entity, newest first, paginated. ?code= gives the merges that kept that record |
POST | /api/v1/entities/:entityId/lookalikes/merges/:mergeId/unmerge | Undo a merge |
Pagination and search
| Parameter | Default | Max | Description |
|---|---|---|---|
page | 1 | — | Page number |
pageSize | 100 | 1000 | Records per page |
search | — | — | Free-text search across code and name |
Examples
1. Discover your entities. This gives you the entityId values the other calls need.
2. Inspect an entity's attributes. Check the attribute ids and data types before you write.
3. Read records.
Records come back as flat objects. A Decimal comes back as a JSON number. Under Decimal values below you find how to get the exact text. A domain attribute carries its row id, plus a _<FieldName>_display property with the readable label:
4. Create a record. The body needs code or name, or both. Pass attribute values in the values array.
5. Update a record. Same body shape. Only the attributes present in values are changed.
6. Delete a record.
Refuse a write when the record changed (ETag and If-Match)
When two clients read the same record and both update it, the second write erases the first. To prevent this, send back the version you read.
1. Read the record. The answer has an ETag header. It is the version of the record, in lowercase hex between quotes.
2. Send it back. Put it in the If-Match header. This works for PUT and for DELETE of the same record.
If the record is still the version you read, the write works. If it changed, nothing is written and the answer is 412:
Read the record again, apply your change to the new values, and send it with the new ETag.
If-Match | Result |
|---|---|
The ETag you read, still current | The write works |
An old ETag | 412 RECORD_CHANGED, nothing written |
Not the form "<16 hex digits>" or * | 400 VALIDATION_ERROR |
* or no header | The write works, as before |
Values array — field names by data type
| Data type | Field in values | Example |
|---|---|---|
| Text | textValue | "textValue": "Gold" |
| Int | intValue | "intValue": 42 |
| Decimal | decimalValue | "decimalValue": 9.99 or "decimalValue": "9.99" |
| Boolean | intValue | "intValue": 1 (1 = true, 0 = false) |
| DateTime | dateTimeValue | "dateTimeValue": "2026-01-15T00:00:00" |
| Domain | domainValue | "domainValue": 5 — the row id of a record of the attribute's target entity. A row id from another entity is refused, and so is a code. See Domain Sources & Links |
Decimal values
A Decimal column holds up to 12 digits before the point and 10 after. Send decimalValue as a number or as a string. Both store the same value. A string is the safe choice for a value of more than 15 digits, because a JSON number cannot hold them.
A read returns a Decimal as a JSON number by default. A JSON number holds about 15 digits, so a longer value is rounded in the answer. Add ?decimals=text to a read to get the exact value as a string, for example /api/v1/entities/7/records/102?decimals=text. It works on the list and on a single record. Any other value of decimals answers 400. A value that is not a number answers 400 VALUE_NOT_ACCEPTED. A value with more than 12 digits before the point answers 400 VALUE_OUT_OF_RANGE.
On an entity that requires approval, "decimalValue": null in an update means "not changed". To clear the field there, send "decimalValue": "". On an entity without approval both null and "" clear the field. A value longer than 400 characters is not a number and answers 400.
Lookalikes in the answer
When Lookalikes is on for the entity, a create or an update answers the codes of the records that look like the saved one:
lookalikeCheck tells you what happened:
| Value | Meaning |
|---|---|
done | The search ran. lookalikes lists the codes, best match first. An empty list means none. |
queued | The search took longer than 2 seconds. lookalikes is null. Primentra checks the record in the background, and the matches show in the Lookalikes queue. |
skipped | You sent ?lookalikes=skip. No search ran. The background check still runs. |
off | Lookalikes is off for this entity. |
Add ?lookalikes=skip to a create or an update when you load many records one at a time and do not need the answer. Any other value of lookalikes answers 400. A column you may not see takes no part in the search. A caller without read access to the entity gets queued and no codes. A change that waits for approval answers 202 without these fields, because no record was saved.
To search without saving, send the values to /lookalikes/search. Name each value by its attribute name, or code and name:
Old codes of merged records
When two records are merged, the code of the record that went away becomes an old code of the record that stays. A read by the old code answers the record that stays, and says so:
A read by a code that is still in use has no mergedInto. A code that no record has, now or before, answers 404.
A link by an old code goes to the record that stays, in an import and in a staging load. A new record with an old code is refused with 409: the code is taken.
Merge and unmerge records
A merge needs the Merge, Update and Delete rights on the entity. An unmerge needs Merge, Create and Update. The API runs the same checks as the Lookalikes screen.
1. Find what to merge. GET /lookalikes/groups lists the open groups, best score first. Each group gives its id, its version, the codes of its records and the pairs with their reasons. Use page, pageSize (at most 100 groups) and minScore.
2. Merge. Name the record to keep and the records to merge into it, by code. picks names, per column, the record whose value the kept record takes. Use the column name, or name for the Name. A column without a pick keeps the value of the kept record. Code is always the code of the kept record.
groupId and version are optional. Send them when you merge a group from step 1: when somebody changed the group since you read it, the merge answers 409 GROUP_CHANGED and changes nothing. With a group, every record must be a member of it. Every link to a merged record, in every model, moves to the kept record. The old codes become old codes of the kept record.
When a Must be close column refuses two of these records, the merge still runs, as it does for a person on the merge screen. The answer then has warnings, with the column and the two codes. On an entity that requires approval, warnings is in the data of the 202 answer. A column you may not see gives no warning.
Primentra compares at most 50 records in one call. With more records it compares nothing, the merge still runs, and warnings holds GATE_NOT_CHECKED. Merge in parts of 50 to get the check.
One call merges up to 1,000 records, the kept record included, in one transaction. A call with more answers 400 TOO_MANY_RECORDS. Merge a larger set in parts, each part into the same kept record.
An old code of a merged record in keep or merge answers 409 CODE_MERGED_AWAY and names the record it was merged into. A code that no record has answers 404. A pick of a column you may not see answers 400 UNKNOWN_COLUMN, the same answer as a column that does not exist. Pick each column once: a second pick for the same column answers 400.
A merge never changes a column you may not see. A default rule does not fill it either: the rule runs on the next save by somebody who sees the column. When that column is empty on the kept record and a required rule sits on it, the merge answers 400 RULE_FAILED and changes nothing. Keep a record that has a value there, or ask somebody who sees the column to fill it.
3. Unmerge. The merge answer gives the mergeId. GET /lookalikes/merges lists the merges, with canUnmerge and, when an unmerge cannot run now, the reason (unmerged, laterMerge, orphaned, pendingApproval).
The merged records come back with their own codes and values. Undo the newest merge of a record first.
A column can change after a merge. Each value then takes the form its column has now, as a data type change converts it: the text 42 comes back as the number 42. When a value does not convert, or a link names a record of another entity than the column's source, the unmerge answers 409 and changes nothing. Change the column back, then undo the merge. A column that was deleted has no place for its values: deletedColumnValues in the answer says how many did not come back.
On an entity that requires approval, a merge and an unmerge answer 202 with the approvalRequestId, as every other write does. Nothing changes until an approver approves the request. Add "note" to the body to tell the approver why.
GET /lookalikes/merges?code= lists the merges that kept that record, and the merges of the records merged into it. Asked for an old code of a chain (A into B, then B into C), it lists both merges.
The Lookalikes calls answer these codes:
| Code | HTTP | Meaning |
|---|---|---|
VALIDATION_ERROR | 400 | The body or the address is not valid, for example no keep, or a mergeId that is not a whole number from 1 to 2,147,483,647 |
TOO_MANY_RECORDS | 400 | More than 1,000 records in one merge call |
TOO_FEW | 400 | The codes name fewer than two different records |
UNKNOWN_COLUMN | 400 | A pick names a column that does not exist or that you may not see |
RULE_FAILED | 400 | The merged record breaks a business rule. Nothing changed |
MERGE_CYCLE | 400 | A record of the merge links to another record of it, for example through a Parent column. Change that link first |
PERMISSION_DENIED | 403 | A right is missing, or a pick writes a column that you may read but not change |
NOT_FOUND | 404 | No record has the code, or no merge has the mergeId |
CODE_MERGED_AWAY | 409 | A code is an old code of a merged record. The message names the record it was merged into |
RECORDS_CHANGED | 409 | A record of the merge no longer exists. Read the group again |
GROUP_CHANGED | 409 | The group changed since you read it. Read it again |
NOT_IN_GROUP | 409 | A record is not a member of the group you sent |
PENDING_APPROVAL | 409 | A record has a request that waits for an approver |
NEEDS_APPROVAL | 409 | The entity needs approval. The API sends the call for approval and answers 202, so you see this code only when the entity changed during the call |
MERGE_BUSY | 409 | Another merge of this entity is running. Try again |
UNMERGE_ORDER | 409 | A later merge of the same record must be undone first, or the merge was undone already |
MERGE_ORPHANED | 409 | The kept record was deleted. The merge can no longer be undone |
CODE_TAKEN | 409 | An unmerge brings back a code that another record uses now. Change that record's code first |
STAGING_RUNNING | 409 | A staging batch of this entity is running. Try again when it ends |
VALUE_DOES_NOT_FIT | 409 | A value that an unmerge must put back does not convert to the data type its column has now. The message names the column and the record, unless the column is hidden for you. Change the column back first |
LINK_OTHER_ENTITY | 409 | A link that an unmerge must put back names a record of another entity than the source its column has now. Change the column back to its earlier source first |
MDS_MIGRATION_RUNNING | 409 | An MDS migration run holds this entity |
A create or an update of a record answers 409 CODE_MERGED_AWAY too, when its code is an old code of a merged record, or when a merge took the record away while the call ran. So do an update and a delete of the id of a merged record: the message names the record it was merged into, and that record does not change. A code that another record uses answers 409 DUPLICATE.
Reading every page
Follow pagination.totalPages until you have them all:
Error codes
| Code | HTTP | Meaning |
|---|---|---|
VALIDATION_ERROR | 400 | Missing required field or invalid input |
VALUE_NOT_ACCEPTED | 400 | The database refused a value. The message names the field, for example a domain id that matches no record |
INVALID_KEY | 401 | Key not found or invalid |
KEY_DISABLED | 401 | The key or its linked user is inactive |
KEY_EXPIRED | 401 | The key is past its expiry date |
PERMISSION_DENIED | 403 | The role lacks the permission for this operation. This includes filling a domain attribute whose source the role cannot read |
LICENSE_EXPIRED | 403 | The license or trial has expired. Reads and exports still work; writes are refused until it is renewed |
NOT_FOUND | 404 | Entity or record does not exist |
RATE_LIMITED | 429 | More than 300 requests in one minute on this key |
API_DISABLED | 503 | The global kill switch is off |
INTERNAL_ERROR | 500 | Unexpected server error |
Approval workflows and the API
When an entity has Requires approval enabled, an API write is offered to an approver instead of being applied. Nothing reaches master data until a person decides on it.
The call is not refused. It answers 202 Accepted:
This applies to all three writes — create, update and delete. A queued delete leaves the record in place until the deletion is approved.
Write your integration to expect it. A 200 means the change is live. A 202 means it is waiting, and approvalRequestId is the number to quote if someone asks what happened to it. Treating 202 as success-and-done is the mistake to avoid: the data is not there yet.
If the submission could never be approved, you get a 400 with the reason instead — a code that already exists, or a value that breaks a blocking business rule. Those are checked at submission rather than left for the approver, who did not type the value and cannot fix it.
Why the API is treated like a person and staging is not
An API key is easy to get: any Primentra administrator makes one in about ten seconds. If a key could write past approval, approval would be optional for anyone who can make a key. So an API write goes to an approver, the same as a change made in the grid.
Staging is different. It needs a SQL login with write rights on the stg schema, it has no user, and it publishes directly. Why staging publishes directly gives the full reasoning, and what it means for who may write to stg.
Every API write is written to the audit log whether it was applied or queued, so the change is traceable either way.
Usage tracking
Every authenticated request is counted per key, with a breakdown by operation.
| Counter | Incremented on |
|---|---|
| Total | Every authenticated request |
| Read | GET |
| Create | POST |
| Update | PUT |
| Delete | DELETE |
The counters appear as R/C/U/D badges in the API Users table, in the dashboard's API keys widget, and as a total API calls card in the dashboard KPIs. Tracking is fire-and-forget and never slows a response.
─── Technical ───
Database tables
| Column | Table | Description |
|---|---|---|
KeyHash | ApiKeys | SHA-256 hash of the raw key. The raw key is never stored |
KeyPrefix | ApiKeys | First 12 characters of the key, shown in the UI |
CallCount | ApiKeys | Incremented on every authenticated request |
LastUsedAt | ApiKeys | Timestamp of the most recent request |
ExpiresAt | ApiKeys | NULL means the key never expires |
IsDeleted | ApiKeys | Soft delete. The row is kept for audit; the key is rejected |
UserType | Users | 'api' for service accounts, 'standard' for people |
Authentication flow
- The client sends
X-API-Key: prm_<key>. - The server hashes the key with SHA-256 and looks the hash up in
ApiKeys. - If the key is valid — not deleted, not inactive, not expired, and the API is not globally disabled — the request proceeds as the linked API user.
CallCountis incremented andLastUsedAtupdated.- Role-based permission checks run exactly as they do for a human user.
Kill switch caching. The apiEnabled setting is cached in memory for 30 seconds. Toggling it in General Settings clears the cache at once, so the change is immediate. The 30-second window only matters when the setting is changed outside the application.
Related
- Staging API Reference: the staging endpoints, for bulk loads the record API is not built for
- Roles & Permissions: what an API user's roles allow
- General Settings: where the API kill switch lives
- Integration Views: reading the same data with SQL
- Audit Log: every API write is recorded there
Further reading
- The Primentra REST API: worked examples of reading and writing master data from another system
Did not find what you need?
Try the troubleshooting pages, or ask us.