Run an action – POST /api/v1/actions/{actionId}/run

Runs a stored action, optionally on a record and with values for its variables. The caller can wait for the result and receive the output parameters, or have the action run in the background. This page is the reference for the operation.

---

1. At a glance

Purpose	Start an action from another system
Method and path	POST /api/v1/actions/{actionId}/run
Typical use	Run "Send welcome mail" for a new customer; start an import or a recalculation; delete a record through an action
Permissions	Valid token. The "Execution Condition" of the action decides whether it runs. A target record must lie within the "Read Limits" of the API user.
Success	200 OK with the result, or with the job number when running in the background
Related	Actions, Action variables, Background processing

---

2. Request

Path parameters

Parameter	Meaning	Required
actionId	ID of the action ("Copy ID" in the management view of the actions)	Yes

Body

{
  "target": { "entityDefId": "6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13", "entityRecId": "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58" },
  "params": { "Reason": "Imported from ERP", "Amount": 1500 },
  "waitForCompletion": true
}

Property	Meaning	Default
target	The record the action runs on: entityDefId (entity) and entityRecId (record). Both are required when target is given.	none – the action runs without a record
params	Values for variables of the action. The key is the ID, the technical name or the display name of the variable (upper and lower case ignored).	none
waitForCompletion	true: wait until the action has finished and return its output parameters. false: put it into the job queue and return at once.	true

Values in params

Action variables have no fixed type. The JSON value is passed on as follows:

JSON value	Arrives in the variable as
String	Text
Whole number	Integer
Decimal number	Double
true / false	Yes/no
null	Empty
Array or object	Its JSON text – for the JSON functions of the expressions

Variables are meant to be handed in when they are marked "Input Parameter". The API does not check this mark: it accepts every variable of the action (see Action variables).

---

3. Response

Waiting for the result – waitForCompletion: true

{
  "actionDefId": "3e9a7b15-6c2d-4f80-a1b3-5d7e9f0c2a46",
  "actionName": "SendWelcomeMail",
  "target": { "entityDefId": "6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13", "entityRecId": "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58" },
  "waitedForCompletion": true,
  "executed": true,
  "executionId": "b0d7c3e1-9a2f-4b6d-8c5e-1f3a7d9b2e40",
  "jobId": null,
  "output": [
    { "variableDefId": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d", "variable": "ResultMessage", "value": "Mail sent to j.miller@acme.example" }
  ]
}

In the background – waitForCompletion: false

{
  "actionDefId": "3e9a7b15-6c2d-4f80-a1b3-5d7e9f0c2a46",
  "actionName": "SendWelcomeMail",
  "target": { "entityDefId": "6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13", "entityRecId": "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58" },
  "waitedForCompletion": false,
  "executed": true,
  "executionId": null,
  "jobId": "421",
  "output": null
}

Property	Meaning
actionDefId, actionName	ID and technical name of the action
target	The record from the request, or null
waitedForCompletion	Whether the request waited
executed	Waiting: true if the action ran, false if its execution condition prevented it (executionId and output are then null). In the background: always true – the job was queued.
executionId	ID of the run (waiting only)
jobId	Number of the job in the job queue (background only)
output	Waiting only: one entry per variable marked "Output Parameter", with ID, technical name and value; an empty list if the action has none

---

4. Behaviour

1. nexxcite looks up the action and resolves the keys of params. An unknown key ends the request with 400 variable_not_found before anything runs.
2. If target is given, the record is read with the "Read Limits" of the API user. A record outside them is reported as 404 record_not_found, and the action does not run.
3. Waiting: the action runs during the request, as the user of the API access. The response follows when it has finished.
4. Background: the action is put into the job queue of the server that received the request and runs there as soon as a worker is free, as the same user. The response follows immediately.

Without a user interface

The action runs without a browser. Commands that need a user interface – dialogs, forms, navigation, messages, input prompts – cannot work and are skipped or end without an answer. Design actions for the API without such commands. See Actions and Background processing.

Execution condition

The "Execution Condition" of the action is evaluated against the target record (or without a record). If it is false, the action does not run: when waiting, the response says "executed": false – with status 200, not an error. The "Execution Condition Error Message" is not returned.

Actions that run against a query

If "Runs Against Query" is set, the action runs once for every record of its query; the target record is ignored. The response then says "executed": true, with executionId and output set to null.

Errors inside the action

The response does not report whether a command inside the action failed. A failed command can still answer "executed": true; output parameters are then not reliable. Check the run in the execution history:

How the action was started	Recorded in Admin Studio → Monitoring → Background Processes
waitForCompletion: false	Always
waitForCompletion: true	Only if "Trace Executions" is on for the action

An unexpected error that stops the action answers 500 server_error.

Who may run which action

Every action whose ID is known can be run through the API. There is no permission per action. The only check is the "Execution Condition" – plus the entity policies for everything the action reads and writes. If an action must not be started from outside, give it an execution condition that is false for the user of the API access.

---

5. Status and error codes

HTTP status	error	Cause
200	–	The action ran, was prevented by its execution condition, or was queued
400	invalid_target	target without entityDefId or entityRecId
400	variable_not_found	A key in params is not a variable of the action
401	–	No valid token
404	action_not_found	No action with this ID
404	entity_not_found, record_not_found	The target entity or record does not exist or is not readable
500	server_error, query_failed	Unexpected error, see Errors

---

6. Examples

Run on a record and wait for the result:

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" } }'

Start an import in the background, with a JSON payload:

curl -X POST https://nexxcite.example.com/api/v1/actions/8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "params": { "Payload": { "orders": [ { "number": "A-20417", "amount": 1500 } ] }, "Source": "ERP" },
        "waitForCompletion": false }'

The variable "Payload" receives the JSON text {"orders":[{"number":"A-20417","amount":1500}]}.

Delete a record: the API has no delete operation. Create an action that deletes its record and run it with the record as target. The "Delete Limits" of the API user apply.

---

7. Limitations

• No permission per action – only the execution condition (section 4).
• Commands that need a user interface do not work.
• Errors of commands are not reported in the response.
• A background job cannot be queried through the API; its result is only visible in Background Processes. Jobs that wait or run on a server are lost when that server stops (see Background processing).
• When waiting, the request stays open until the action has finished. Proxies or load balancers in front of nexxcite may end long requests earlier; use waitForCompletion: false for long actions.

---

8. Related pages

• Actions
• Action variables
• Background processing
• Errors