REST API – connecting other systems to nexxcite¶

The REST API lets another system – an ERP, a web shop, an integration platform or a script – work with nexxcite over HTTPS: create, read, update and search records, and run actions. This chapter is the reference for the API. It is intended for administrators who set up interfaces and for the people who build the calling system.

How an administrator creates the access for such a system (the API access, its client secrets and the user it runs as) is described in API access and credentials.

1. The REST API at a glance¶

Operation	Method and path	Page
Request an access token	`POST /api/oauth/token`	Authentication
Create a record	`POST /api/v1/records/{entityId}`	Create a record
Update a record	`POST /api/v1/records/{entityId}/{recordId}`	Update a record
Read a record, optionally with related records	`GET /api/v1/records/{entityId}/{recordId}`	Read a record
Search records	`POST /api/v1/records/{entityId}/query`	Query records
Run an action	`POST /api/v1/actions/{actionId}/run`	Run an action
Interactive description	`GET /api/v1/docs` (no token needed)	Section 7

Further pages: Fields and values (how fields are named and values are written) and Errors (every status and error code).

Summary¶

The caller requests an access token with the client ID and a client secret of an API access, and sends it with every request.
Every request runs as the user assigned to the API access – with that user's roles, entity policies and license. The API cannot do more than this user could do.
Records are written through the same business logic as in a form: calculation rules, default values, validations and the rules that run before and after saving apply.
The API works on records and actions. Definitions (entities, forms, actions themselves) cannot be read or changed through it.

2. Base address and versions¶

All addresses are relative to the address of your nexxcite installation, for example https://nexxcite.example.com.

Part	Address
Token endpoint	`https://<your installation>/api/oauth/token`
Records and actions	`https://<your installation>/api/v1/...`

The v1 in the path is the version of the API. An incompatible change would be published under a new version next to the current one. The token endpoint has no version.

Use HTTPS. Where HTTPS is set up, nexxcite redirects a request over plain HTTP to HTTPS – and many HTTP clients do not repeat a POST body after such a redirect.

3. Authentication at a glance¶

An administrator sets up an API access and gives you its client ID and a client secret (see API access and credentials).
Your system requests a token: POST /api/oauth/token with grant_type=client_credentials.
It sends the token with every request in the header Authorization: Bearer <token>.
The token is valid for one hour by default (expires_in in the answer). Reuse it until then and request a new one afterwards.

Details, error codes and the effects on sessions and licenses: Authentication.

4. Conventions¶

Topic	Rule
Format	Requests and responses are JSON (`Content-Type: application/json`). Only the token endpoint expects a form (`application/x-www-form-urlencoded`).
Property names	camelCase, for example `entityRecId`. Upper and lower case of property names is ignored in requests.
IDs	Entities, records, relationships, actions and variables are identified by IDs in GUID form, for example `6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13`. You copy the ID of a definition with "Copy ID" in its management view in the Admin Studio.
Fields	By ID, technical name, storage name or display name – see Fields and values.
Dates	ISO 8601: `2026-03-04` for dates, `2026-03-04T14:30:00` for date and time.
Numbers and yes/no	JSON numbers and `true` / `false`. Numbers may also be sent as text (`"1500.50"`, decimal point).
Empty values	`null` empties a field. In responses, properties without a value are written as `null`.
Paging	Only queries return lists: `page.limit` (default 50, at most 1000) and `page.skip`. The response contains the total number of hits.
Errors	JSON with a stable code in `error` and a text in `errorDescription` – see Errors.

Note: Values you send are always stored as they are. A text such as [[sf(CurrentUserId)]] is not evaluated as an expression.

5. Permissions¶

There is no separate permission for the REST API. What a call may do is decided by the user of the API access:

What	Decided by
Which records can be read and found	The "Read Limits" of the user's roles. A record outside them is reported as not found.
Whether a record may be created	The "Add Limits"
Whether a record may be changed	The "Edit Limits"
Which fields can be read and written	The "Field Limits" of the user's roles. A field with access "Denied" is returned empty. A value sent for a field the user may not change is discarded without an error.
Whether an action may run	Only the "Execution Condition" of the action (see Run an action)

Users with "System Developer" are not restricted by add and edit limits, read limits apply to them as well (see Roles and permissions). Give the user of an API access a role of its own with exactly the limits the external system needs.

6. Licenses and limits¶

Topic	Behaviour
License	A token takes a license for the user of the API access, like a browser sign-in – unless that user already has one through another session or has a license-free role. See Licensing.
All licenses in use	No token is issued: `400` with `temporarily_unavailable`. Try again later.
No valid license	Every API request, the token endpoint included, is answered with `503` and `license_invalid`.
Number of requests	Not limited by nexxcite. There is no rate limit on the API or the token endpoint.
Records per query	At most 1000 per request; use `page.skip` for more.
Request duration	Not limited by nexxcite. A long-running action with `waitForCompletion` keeps the request open; proxies and load balancers in front of nexxcite may end it earlier (our assessment – check their timeout settings).

For the calling system

Reuse the token until it expires. Every token request creates a new API session; requesting a token per call fills the session list and is slower.
Request a new token when a call returns 401, and retry the call once.

7. Interactive description (OpenAPI)¶

nexxcite describes the API itself:

Address	Content
`/api/v1/docs`	Interactive documentation in the browser. "Authorize" lets you request a token with client ID and secret (`clientCredentials`) or paste an existing token (`bearerAuth`); afterwards every operation can be tried out.
`/api/v1/openapi.json`	The OpenAPI description, for code generators and API tools

Both addresses can be opened without a token; the operations themselves still need one. An operator can switch both off with ApiDocumentation:Enabled = false or move them (see Installation and configuration); the API keeps working.

The interactive documentation keeps an entered token in the browser until you log out of it with "Authorize" → "Logout". Use it on your own computer only.

8. Example from start to finish¶

An ERP system creates a customer, finds it again and runs the action "Send welcome mail" on it.

1. Request a token

curl -X POST https://nexxcite.example.com/api/oauth/token \
  -u "Zx8nQ2vLr5TfK1wE:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials"

{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600 }

2. Create the customer

curl -X POST https://nexxcite.example.com/api/v1/records/6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "fields": [ { "field": "CustomerNumber", "value": "K-1001" },
                    { "field": "Name", "value": "ACME Ltd." } ] }'

The answer (201 Created) contains the new record with its ID in entityRecId, for example 9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58.

3. Find it again

curl -X POST https://nexxcite.example.com/api/v1/records/6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": { "type": "field", "field": "CustomerNumber", "operator": "equals", "value": "K-1001" },
        "fields": ["CustomerNumber", "Name"] }'

4. Run the action on it

curl -X POST https://nexxcite.example.com/api/v1/actions/3e9a7b15-6c2d-4f80-a1b3-5d7e9f0c2a46/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "target": { "entityDefId": "6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13",
                    "entityRecId": "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58" } }'

The answer reports whether the action ran and the values of its output parameters.

9. Limitations¶

Records cannot be deleted through the API. Use an action that deletes the record and run it through the API.
Files and images of records cannot be uploaded or downloaded.
There are no operations to list entities, fields or actions. The IDs come from the Admin Studio ("Copy ID").
Several records cannot be written in one request, and several requests do not form a transaction.
Related records can be read with a record, but not written together with it.
Only the OAuth 2.0 client credentials method is supported (see Authentication).

10. Frequently asked questions¶

Does the API respect the entity policies of the user? Yes. Read, add and edit limits of the user of the API access apply exactly as in the browser.

Do business rules run when a record is written through the API? Yes. Records are written by the same logic as in a form, including calculation rules, validations and rules that run before and after saving.

Can the API change definitions, for example add a field? No. The API works on records and actions only.

Is there a limit on the number of requests? No. nexxcite does not limit the number of requests. Protect the installation with a proxy or gateway if you need such a limit.

Does an API call take a license? Yes, through its token – unless the user has a license-free role or already holds a license.

API access and credentials – setting up the access
Roles and permissions – entity policies
Licensing – licenses of API sessions
Background processing – actions started without waiting