The Primentra REST API: read and write master data from any system

{
  "success": true,
  "data": [
    {
      "id": 101,
      "code": "CUST-001",
      "name": "Acme Corp"
    }
  ],
  "pagination": {
    "total": 542 }
}

Master data is only useful if other systems can get to it. That sounds obvious, but it is worth saying: an MDM tool that only exposes data through its own UI is, at best, a well-organized dead end. At worst, it becomes the bottleneck — every downstream system that needs a product code, cost centre, or country list ends up either polling a database view, maintaining a manual export schedule, or just duplicating the data and accepting the drift.

Primentra has always had integration views — SQL views in the [mdm] schema that BI tools and ETL pipelines can query directly. They work well for read-heavy, scheduled-batch scenarios. The underlying data model — models, entities, and attributes — is the same structure the API exposes. But not every integration fits that shape. Some need to write back. Some need to trigger on demand. Some are running on systems that cannot talk SQL Server at all.

That is what the REST API is for.

What the API does

The Primentra REST API exposes your entity records over HTTP. Every endpoint is under /api/v1/ and requires an X-API-Key header. Authentication is server-to-server only — no CORS, no browser-based calls from external origins.

The full endpoint set:

Responses follow a consistent envelope: { "success": true, "data": [...], "pagination": { "page": 1, "total": 542 } }. Errors include a machine-readable code and a human-readable message.

What you can build with it

A few integrations that become straightforward:

• ETL pipelines: Read master data at the start of a pipeline run, or push newly validated records back after transformation. No SQL Server access required on the ETL side.
• ERP write-back: When a data steward approves a new cost centre in Primentra, a webhook or scheduled job calls the API to sync it into your ERP the same day — not the next batch cycle.
• Custom internal tooling: Internal apps that need dropdown values from your MDM (product categories, country codes, GL accounts) can call the API instead of maintaining a local copy.
• Data validation services: Before accepting an order or invoice, call the API to check if a given product code or supplier ID actually exists in master data.
• Monitoring and reporting: Pull entity record counts, last-modified timestamps, or specific field values into dashboards that track data health.

Here is what a basic read looks like — list all records in an entity, search for a specific value:

# List records — first page, search by name
curl "https://your-server/api/v1/entities/3/records?search=Acme" \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34"

# Create a record
curl -X POST https://your-server/api/v1/entities/3/records \
  -H "X-API-Key: prm_Ab12XyZwQrstUv34" \
  -H "Content-Type: application/json" \
  -d '{"code":"CUST-050","name":"Acme Corp","values":[
        {"attributeId":12,"intValue":5},
        {"attributeId":13,"textValue":"Gold"}
      ]}'

Permissions: one model, two types of user

API users are service accounts, not a separate access system. They sit inside the same role and permission model as regular users. You create an API user in Access Management → API Users, assign it one or more roles, and those roles carry the exact same read/create/update/delete permissions that govern what a human user with those roles can do.

If a role grants read access to the Customer entity but not write access, an API key assigned to that role will receive 403 Forbidden on any POST or PUT to that entity. There is no way to give an API key permissions that a role does not grant.

This matters in practice. It means you can apply the same access design you already use for people — create a purpose-built role for each integration (read-only for the BI connector, write access only to the Supplier entity for the procurement system) and assign it to the corresponding API user. You are not working around your access model or punching holes through it.

API users can be deactivated or have their keys regenerated at any time without affecting other users or integrations. A compromised key is addressed in under a minute.

Auditing: every change is attributed

Every write operation through the API — create, update, delete — is recorded in Primentra's audit log and attributed to the named API user. You will see entries like "Customer CUST-050 created by Procurement Sync" with the full timestamp and previous/new values. This is the same audit log that captures human edits and approval workflow decisions, so there is one place to look for the full history of a record regardless of how the change was made.

Each API key also tracks a call count and a last-used timestamp. These update on every authenticated request, so you can tell immediately if an integration has gone quiet — a key that was making hundreds of daily calls and suddenly shows "Last used: 14 days ago" is worth investigating.

For regulated environments, this matters. When an auditor asks "who changed this cost centre code on the 14th?", the answer is either a person's name or a service account's name — not "probably a script."

The kill switch

There is a global API toggle in Admin → General Settings → API. When it is off, every request with an X-API-Key header returns 503 Service Unavailable immediately — no key validation, no database lookup. All keys and users are preserved and resume working when you switch it back on.

This is useful during maintenance windows, incident response, or while rolling out a new model structure that would break existing integrations. You can take everything offline in one toggle rather than tracking down and deactivating individual keys.

Getting started

The setup takes about two minutes:

1. Go to Admin → Access Management → API Users
2. Click New API user, give it a name, assign a role
3. Copy the generated key — it is only shown once
4. Add X-API-Key: prm_<your-key> to your HTTP client
5. Call GET /api/v1/entities to see what entities you have access to

The API documentation is in the in-app help (Help → Administration → API Keys) and includes working curl, Python, and JavaScript examples with the full attribute value format explained.

Common questions