Actions

How to use it

When you are ready to perform an action, you can use the operate method by making a POST call:

// (POST) api/users/actions/send-welcome-notification
{
    "fields": [
      { "name": "expires_at", "value": "2023-04-29" }
    ]
}

You may specify the fields provided by the user using the fields argument. You can have full access to the fields and validation in the resource details.

send-welcome-notification is the uriKey of the action provided in the resource details.

As a response, you'll receive the number of models that were impacted:

{
  "data": {
    "impacted": 150
  }
}

Complex filtering

In most cases you'll want to specify which models will be dynamically impacted by the action. The action endpoint provides full support for the search operation. If you are not familiar with the search method, have a quick look at the documentation.

Specify your arguments in the search argument:

// (POST) api/users/actions/send-welcome-notification
{
    "fields": [
      { "name": "expires_at", "value": "2023-04-29" }
    ],
    "search": {
        "filters": [
            { "field": "has_received_welcome_notification", "value": false }
        ]
    }
}

Targeting models explicitly

When you already know which models the action applies to, an action declared as targeted takes the list of ids in the resources argument instead of a search:

// (POST) api/users/actions/deactivate-users
{
    "resources": [1, 5, 9],
    "fields": [
      { "name": "reason", "value": "spam" }
    ]
}

resources is required on a targeted action, and a search is prohibited on it, so the action can never impact every model because the caller forgot to narrow it down. Omitting resources, passing an empty array, naming an id that does not exist, or passing more ids than the action accepts all return a 422 response.

Ids the current user is not allowed to see are silently skipped, since the resource's search query still constrains the targeted models.

Response

As a response you'll receive the number of models that were impacted.

{
  "data": {
    "impacted": 2
  }
}

Targeting states

An action has exactly one of three targeting states, which decides what its request body may carry. The details endpoint exposes the state through the standalone and targeted keys of each action.

Standalone actions

A standalone action is an action that does not require any models to run. You may know if an action is standalone in the detail endpoint with the standalone key.

Standalone actions works the same, you just can't specify a search operation.