Documentation
Use Primentra
Getting Started
Data Grid
Approvals
Set up
Modeling
Business Rules
Users & Roles
Sign-in & Security
Install and run
Installation
Administration
Integration & API
Architecture
Migrate from MDS
Migrating from MDS

REST API

On this page

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.

The API Users tab under Access Management, listing each service account with its key prefix, roles, status and call count
The API Users tab under Access Management, listing each service account with its key prefix, roles, status and call count(click to enlarge)

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 Primentra REST API — API keys, permissions and the kill switch

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-Key returns 503 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:

  1. Click New API user.
  2. Enter a display name. This field is required.
  3. Optionally name the key. A label helps when you manage several.
  4. Assign one or more roles.
  5. Optionally set a key expiry date. Leave it blank for a key that never expires.
  6. 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:

X-API-Key: prm_<your-key>

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:

{
  "success": true,
  "data": { },
  "pagination": { "page": 1, "pageSize": 100, "total": 542, "totalPages": 6 }
}

Errors return:

{ "success": false, "error": { "code": "PERMISSION_DENIED", "message": "..." } }

Endpoints

Entities

MethodPathDescription
GET/api/v1/entitiesList the entities the API user can read
GET/api/v1/entities/:entityIdEntity metadata and attribute definitions

Records

MethodPathDescription
GET/api/v1/entities/:entityId/recordsList records, paginated
GET/api/v1/entities/:entityId/records/:recordIdOne record
GET/api/v1/entities/:entityId/records/by-code/:codeOne record, found by its code
POST/api/v1/entities/:entityId/recordsCreate a record
PUT/api/v1/entities/:entityId/records/:recordIdUpdate a record
DELETE/api/v1/entities/:entityId/records/:recordIdDelete a record
POST/api/v1/entities/:entityId/lookalikes/searchRecords that look like the values you send. Saves nothing

Lookalikes: merge and unmerge

MethodPathDescription
GET/api/v1/entities/:entityId/lookalikes/groupsOpen groups of lookalikes, best score first, paginated
POST/api/v1/entities/:entityId/lookalikes/mergeMerge records into one, by code
GET/api/v1/entities/:entityId/lookalikes/mergesMerges of the entity, newest first, paginated. ?code= gives the merges that kept that record
POST/api/v1/entities/:entityId/lookalikes/merges/:mergeId/unmergeUndo a merge
ParameterDefaultMaxDescription
page1—Page number
pageSize1001000Records 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.

curl https://your-primentra-server/api/v1/entities \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34"
{
  "success": true,
  "data": [
    { "id": 3, "name": "Customer", "modelId": 1, "modelName": "CRM" },
    { "id": 7, "name": "Product",  "modelId": 2, "modelName": "Products" }
  ]
}

2. Inspect an entity's attributes. Check the attribute ids and data types before you write.

curl https://your-primentra-server/api/v1/entities/3 \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34"
{
  "success": true,
  "data": {
    "id": 3,
    "name": "Customer",
    "attributes": [
      { "id": 12, "name": "Region", "dataType": "Domain", "isRequired": true },
      { "id": 13, "name": "Tier", "dataType": "Text", "isRequired": false },
      { "id": 14, "name": "IsActive", "dataType": "Boolean", "isRequired": false }
    ]
  }
}

3. Read records.

curl "https://your-primentra-server/api/v1/entities/3/records?pageSize=50" \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34"

curl "https://your-primentra-server/api/v1/entities/3/records?search=Acme" \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34"

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:

{
  "id": 101,
  "code": "CUST-001",
  "name": "Acme Corp",
  "createdAt": "2026-02-01T09:14:00",
  "modifiedAt": "2026-08-10T11:02:00",
  "Region": 5,
  "_Region_display": "{EU} Europe",
  "Tier": "Gold",
  "IsActive": 1
}

4. Create a record. The body needs code or name, or both. Pass attribute values in the values array.

curl -X POST https://your-primentra-server/api/v1/entities/3/records \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "CUST-050",
    "name": "New Customer Ltd",
    "values": [
      { "attributeId": 12, "domainValue": 5 },
      { "attributeId": 13, "textValue": "Silver" },
      { "attributeId": 14, "intValue": 1 }
    ]
  }'

5. Update a record. Same body shape. Only the attributes present in values are changed.

curl -X PUT https://your-primentra-server/api/v1/entities/3/records/102 \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34" \
  -H "Content-Type: application/json" \
  -d '{ "code": "CUST-050", "name": "New Customer Ltd",
        "values": [ { "attributeId": 13, "textValue": "Gold" } ] }'

6. Delete a record.

curl -X DELETE https://your-primentra-server/api/v1/entities/3/records/102 \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34"

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.

curl -i https://your-primentra-server/api/v1/entities/3/records/102 \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34"
HTTP/1.1 200 OK
ETag: "00000000000008e0"

2. Send it back. Put it in the If-Match header. This works for PUT and for DELETE of the same record.

curl -X PUT https://your-primentra-server/api/v1/entities/3/records/102 \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "00000000000008e0"' \
  -d '{ "code": "CUST-050", "name": "New Customer Ltd",
        "values": [ { "attributeId": 13, "textValue": "Gold" } ] }'

If the record is still the version you read, the write works. If it changed, nothing is written and the answer is 412:

{ "success": false, "error": { "code": "RECORD_CHANGED", "message": "The record changed after you read it." } }

Read the record again, apply your change to the new values, and send it with the new ETag.

If-MatchResult
The ETag you read, still currentThe write works
An old ETag412 RECORD_CHANGED, nothing written
Not the form "<16 hex digits>" or *400 VALIDATION_ERROR
* or no headerThe write works, as before
Note: The header is optional, so existing integrations keep working. The bulk API, staging and imports do not check it. The last write wins there.

Values array — field names by data type

Data typeField in valuesExample
TexttextValue"textValue": "Gold"
IntintValue"intValue": 42
DecimaldecimalValue"decimalValue": 9.99 or "decimalValue": "9.99"
BooleanintValue"intValue": 1 (1 = true, 0 = false)
DateTimedateTimeValue"dateTimeValue": "2026-01-15T00:00:00"
DomaindomainValue"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:

{ "success": true, "data": { "id": 102, "lookalikes": ["CUST-001"], "lookalikeCheck": "done" } }

lookalikeCheck tells you what happened:

ValueMeaning
doneThe search ran. lookalikes lists the codes, best match first. An empty list means none.
queuedThe search took longer than 2 seconds. lookalikes is null. Primentra checks the record in the background, and the matches show in the Lookalikes queue.
skippedYou sent ?lookalikes=skip. No search ran. The background check still runs.
offLookalikes 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:

curl -X POST https://your-primentra-server/api/v1/entities/3/lookalikes/search \
  -H "X-API-Key: prm_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "values": { "name": "Acme Corporation", "City": "Utrecht" } }'
{ "success": true, "data": { "lookalikeCheck": "done", "matches": [ { "id": 101, "code": "CUST-001", "score": 96.5, "band": "auto" } ] } }

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:

curl https://your-primentra-server/api/v1/entities/3/records/by-code/CUST-007 \
  -H "X-API-Key: prm_<your-key>"
{ "success": true, "data": { "id": 101, "code": "CUST-001", "name": "Acme Corp" },
  "mergedInto": "CUST-001", "message": "CUST-007 was merged into CUST-001." }

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.

curl -X POST https://your-primentra-server/api/v1/entities/3/lookalikes/merge \
  -H "X-API-Key: prm_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "keep": "CUST-001", "merge": ["CUST-007", "CUST-019"],
        "picks": { "City": "CUST-007", "name": "CUST-001" },
        "groupId": 412, "version": "00000000000A3F21" }'
{ "success": true, "data": { "mergeId": 88, "kept": "CUST-001", "merged": ["CUST-007", "CUST-019"],
  "referencesMoved": 14, "childrenMoved": 0 } }

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.

{ "code": "GATE_REFUSES_PAIR", "column": "Branch number", "codes": ["CUST-001", "CUST-019"],
  "message": "CUST-001 and CUST-019 differ too much in Branch number, a Must be close column." }

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

curl -X POST https://your-primentra-server/api/v1/entities/3/lookalikes/merges/88/unmerge \
  -H "X-API-Key: prm_<your-key>"

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:

CodeHTTPMeaning
VALIDATION_ERROR400The 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_RECORDS400More than 1,000 records in one merge call
TOO_FEW400The codes name fewer than two different records
UNKNOWN_COLUMN400A pick names a column that does not exist or that you may not see
RULE_FAILED400The merged record breaks a business rule. Nothing changed
MERGE_CYCLE400A record of the merge links to another record of it, for example through a Parent column. Change that link first
PERMISSION_DENIED403A right is missing, or a pick writes a column that you may read but not change
NOT_FOUND404No record has the code, or no merge has the mergeId
CODE_MERGED_AWAY409A code is an old code of a merged record. The message names the record it was merged into
RECORDS_CHANGED409A record of the merge no longer exists. Read the group again
GROUP_CHANGED409The group changed since you read it. Read it again
NOT_IN_GROUP409A record is not a member of the group you sent
PENDING_APPROVAL409A record has a request that waits for an approver
NEEDS_APPROVAL409The 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_BUSY409Another merge of this entity is running. Try again
UNMERGE_ORDER409A later merge of the same record must be undone first, or the merge was undone already
MERGE_ORPHANED409The kept record was deleted. The merge can no longer be undone
CODE_TAKEN409An unmerge brings back a code that another record uses now. Change that record's code first
STAGING_RUNNING409A staging batch of this entity is running. Try again when it ends
VALUE_DOES_NOT_FIT409A 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_ENTITY409A 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_RUNNING409An 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:

import requests

BASE = "https://your-primentra-server/api/v1"
HEADERS = {"X-API-Key": "prm_Ab12XyZwQrstUv34"}

page, records = 1, []
while True:
    r = requests.get(f"{BASE}/entities/3/records", headers=HEADERS,
                     params={"page": page, "pageSize": 500}).json()
    records.extend(r["data"])
    if page >= r["pagination"]["totalPages"]:
        break
    page += 1

Error codes

CodeHTTPMeaning
VALIDATION_ERROR400Missing required field or invalid input
VALUE_NOT_ACCEPTED400The database refused a value. The message names the field, for example a domain id that matches no record
INVALID_KEY401Key not found or invalid
KEY_DISABLED401The key or its linked user is inactive
KEY_EXPIRED401The key is past its expiry date
PERMISSION_DENIED403The role lacks the permission for this operation. This includes filling a domain attribute whose source the role cannot read
LICENSE_EXPIRED403The license or trial has expired. Reads and exports still work; writes are refused until it is renewed
NOT_FOUND404Entity or record does not exist
RATE_LIMITED429More than 300 requests in one minute on this key
API_DISABLED503The global kill switch is off
INTERNAL_ERROR500Unexpected 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:

{
  "success": true,
  "status": "pending_approval",
  "approvalRequestId": 41,
  "message": "This entity requires approval, so the record was not applied. It is waiting for an approver as request 41.",
  "data": { "approvalRequestId": 41 }
}

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.

CounterIncremented on
TotalEvery authenticated request
ReadGET
CreatePOST
UpdatePUT
DeleteDELETE

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

ColumnTableDescription
KeyHashApiKeysSHA-256 hash of the raw key. The raw key is never stored
KeyPrefixApiKeysFirst 12 characters of the key, shown in the UI
CallCountApiKeysIncremented on every authenticated request
LastUsedAtApiKeysTimestamp of the most recent request
ExpiresAtApiKeysNULL means the key never expires
IsDeletedApiKeysSoft delete. The row is kept for audit; the key is rejected
UserTypeUsers'api' for service accounts, 'standard' for people

Authentication flow

  1. The client sends X-API-Key: prm_<key>.
  2. The server hashes the key with SHA-256 and looks the hash up in ApiKeys.
  3. 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.
  4. CallCount is incremented and LastUsedAt updated.
  5. 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.

Further reading