> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search ProactiveActionConfigs

> Search and list ProactiveActionConfig records with filtering, sorting, and pagination.

A ProactiveActionConfig is the settings row for one proactive AI agent at one location: whether it runs at all, whether it may act without human review and above what confidence, how many actions it may raise per day, how long it waits before repeating itself, which delivery channel it prefers, and any custom drafting or voice prompts. There is at most one row per location and CriteriaType, and an agent with no row is off. The default posture is human-in-the-loop: the agent raises ProposedAction records into the operator AI Inbox for review, and only turning on AutoExecute lets sufficiently confident actions go out unattended.

## Authentication

<Note>
  This endpoint requires OAuth2 authentication. Include a valid bearer token in the `Authorization` header.
  The authenticated user must be a full unrestricted administrator or have the **`ProactiveActionConfig-List`** role.
</Note>

## Enums

<Accordion title="eOutboundChannel">
  | Value | Name            |
  | ----- | --------------- |
  | 1     | Email           |
  | 2     | Voice           |
  | 3     | CoworkerMessage |
  | 4     | HelpDesk        |
  | 5     | WhatsApp        |
</Accordion>

## Query Parameters

### Pagination & Sorting

<ParamField query="page" type="integer" default="1">
  The page number to retrieve.
</ParamField>

<ParamField query="size" type="integer" default="25">
  The number of records per page.
</ParamField>

<ParamField query="orderBy" type="string">
  The property name to sort results by (e.g. `Name`, `CreatedOn`).
</ParamField>

<ParamField query="dir" type="integer">
  Sort direction. `0` for ascending, `1` for descending.
</ParamField>

### Filters

<ParamField query="ProactiveActionConfig_Business" type="integer">
  Filter by iD of the location this agent configuration applies to. Each location holds at most one configuration per CriteriaType, and an agent with no configuration row is treated as off..
</ParamField>

<ParamField query="ProactiveActionConfig_CriteriaType" type="string">
  Filter by name of the proactive agent this configuration governs, matching a criteria evaluator: DueInvoiceCriteria, ContractExpiryCriteria, SupportPatternCriteria, SupportIssueCategoryCriteria or MissingFaqCriteria. Unique per location; the actions it produces carry the same value in ProposedAction.CriteriaType..
</ParamField>

<ParamField query="ProactiveActionConfig_Enabled" type="boolean">
  Filter by whether this agent runs for the location. When false, or when no configuration row exists at all, the agent is skipped entirely and proposes nothing..
</ParamField>

<ParamField query="ProactiveActionConfig_AutoExecute" type="boolean">
  Filter by whether this agent may act without human review. When true, an action whose confidence reaches AutoExecuteMinConfidence is delivered straight away and recorded as AutoExecuted; anything below it still lands in the inbox. Internal-alert agents ignore this..
</ParamField>

<ParamField query="ProactiveActionConfig_AutoExecuteMinConfidence" type="number">
  Filter by confidence an action must reach before AutoExecute will send it without review, on a 0.0–1.0 scale (not a percentage). Defaults to 0.85. Has no effect while AutoExecute is false..
</ParamField>

<ParamField query="ProactiveActionConfig_MaxActionsPerDay" type="integer">
  Filter by cap on how many actions this agent may raise for the location in a single day; it also caps how many candidates one evaluation run will consider. Empty means uncapped, in which case a run still considers at most 20 candidates..
</ParamField>

<ParamField query="ProactiveActionConfig_CooldownHours" type="integer">
  Filter by how long the agent waits before raising the same trigger again, in hours; defaults to 24. A candidate is skipped when a non-expired action with the same deduplication key was created inside this window, so in practice it throttles repeat outreach about the same invoice, contract or customer..
</ParamField>

<ParamField query="ProactiveActionConfig_ChannelPreference" type="integer">
  Filter by overrides the delivery channel this agent proposes: Email, Voice, CoworkerMessage, HelpDesk or WhatsApp. Empty leaves the choice to the agent's own default. Voice requires the location's AI voice channel to be enabled, and WhatsApp requires a configured WhatsApp number..
</ParamField>

<ParamField query="ProactiveActionConfig_CustomPromptOverride" type="string">
  Filter by extra drafting instructions for this agent, up to 2000 characters, appended to its built-in prompt — for example a tone or signature convention. Starting the text with "OVERRIDE:" (case-insensitive) replaces the agent's whole prompt template instead of adding to it..
</ParamField>

<ParamField query="ProactiveActionConfig_FirstMessage" type="string">
  Filter by opening line spoken or sent when this agent starts an outbound conversation, up to 500 characters. Supports \{\{variable}} placeholders such as \{\{company\_name}} plus the agent-specific variables listed by the criteria-variables endpoint. Empty uses the built-in opening..
</ParamField>

<ParamField query="ProactiveActionConfig_SystemPrompt" type="string">
  Filter by voice-agent system prompt for outbound conversations this agent starts, up to 2000 characters. By default the text is added to the standard prompt; starting it with "OVERRIDE:" (case-insensitive) replaces the standard prompt entirely, and the server then rejects the save unless the text also contains the \{\{voice\_message}} placeholder..
</ParamField>

<ParamField query="ProactiveActionConfig_CriteriaConfiguration" type="string">
  Filter by agent-specific thresholds as a flat JSON object of string values, keyed by the parameter keys the criteria-parameters endpoint publishes for this CriteriaType — for example reminder day counts, minimum invoice amounts or ticket thresholds. Empty means every parameter falls back to its published default..
</ParamField>

### Range Filters

<ParamField query="from_ProactiveActionConfig_AutoExecuteMinConfidence" type="number">
  Filter by confidence an action must reach before AutoExecute will send it without review, on a 0.0–1.0 scale (not a percentage). Defaults to 0.85. Has no effect while AutoExecute is false. greater than or equal to this value.
</ParamField>

<ParamField query="to_ProactiveActionConfig_AutoExecuteMinConfidence" type="number">
  Filter by confidence an action must reach before AutoExecute will send it without review, on a 0.0–1.0 scale (not a percentage). Defaults to 0.85. Has no effect while AutoExecute is false. less than or equal to this value.
</ParamField>

<ParamField query="from_ProactiveActionConfig_MaxActionsPerDay" type="integer">
  Filter by cap on how many actions this agent may raise for the location in a single day; it also caps how many candidates one evaluation run will consider. Empty means uncapped, in which case a run still considers at most 20 candidates. greater than or equal to this value.
</ParamField>

<ParamField query="to_ProactiveActionConfig_MaxActionsPerDay" type="integer">
  Filter by cap on how many actions this agent may raise for the location in a single day; it also caps how many candidates one evaluation run will consider. Empty means uncapped, in which case a run still considers at most 20 candidates. less than or equal to this value.
</ParamField>

<ParamField query="from_ProactiveActionConfig_CooldownHours" type="integer">
  Filter by how long the agent waits before raising the same trigger again, in hours; defaults to 24. A candidate is skipped when a non-expired action with the same deduplication key was created inside this window, so in practice it throttles repeat outreach about the same invoice, contract or customer. greater than or equal to this value.
</ParamField>

<ParamField query="to_ProactiveActionConfig_CooldownHours" type="integer">
  Filter by how long the agent waits before raising the same trigger again, in hours; defaults to 24. A candidate is skipped when a non-expired action with the same deduplication key was created inside this window, so in practice it throttles repeat outreach about the same invoice, contract or customer. less than or equal to this value.
</ParamField>

<ParamField query="from_ProactiveActionConfig_CreatedOn" type="string">
  Filter records created on or after this date. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="to_ProactiveActionConfig_CreatedOn" type="string">
  Filter records created on or before this date. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="from_ProactiveActionConfig_UpdatedOn" type="string">
  Filter records updated on or after this date. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="to_ProactiveActionConfig_UpdatedOn" type="string">
  Filter records updated on or before this date. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

## Code Examples

### Simple listing

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://spaces.nexudus.com/api/sys/proactiveactionconfigs?page=1&size=15&orderBy=CriteriaType&dir=0" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://spaces.nexudus.com/api/sys/proactiveactionconfigs?' + new URLSearchParams({
      page: 1,
      size: 15,
      orderBy: 'CriteriaType',
      dir: 1 // Ascending
    }),
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://spaces.nexudus.com/api/sys/proactiveactionconfigs',
      params={
          'page': 1,
          'size': 15,
          'orderBy': 'CriteriaType',
          'dir': 0 // Ascending
      },
      headers={
          'Authorization': 'Bearer YOUR_TOKEN'
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Filtering by CriteriaType

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://spaces.nexudus.com/api/sys/proactiveactionconfigs?ProactiveActionConfig_CriteriaType=example-value&orderBy=CriteriaType&dir=0" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://spaces.nexudus.com/api/sys/proactiveactionconfigs?' + new URLSearchParams({
      ProactiveActionConfig_CriteriaType: 'example-value',
      orderBy: 'CriteriaType',
      dir: 1
    }),
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://spaces.nexudus.com/api/sys/proactiveactionconfigs',
      params={
          'ProactiveActionConfig_CriteriaType': 'example-value',
          'orderBy': 'CriteriaType',
          'dir': 0 // Ascending
      },
      headers={
          'Authorization': 'Bearer YOUR_TOKEN'
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Range filters

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://spaces.nexudus.com/api/sys/proactiveactionconfigs?from_ProactiveActionConfig_UpdatedOn=2025-01-01T00:00&to_ProactiveActionConfig_UpdatedOn=2025-12-31T23:59&orderBy=UpdatedOn&dir=0" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://spaces.nexudus.com/api/sys/proactiveactionconfigs?' + new URLSearchParams({
      from_ProactiveActionConfig_UpdatedOn: '2025-01-01T00:00',
      to_ProactiveActionConfig_UpdatedOn: '2025-12-31T23:59',
      orderBy: 'UpdatedOn',
      dir: 1 // Descending
     }),
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://spaces.nexudus.com/api/sys/proactiveactionconfigs',
      params={
          'from_ProactiveActionConfig_UpdatedOn': '2025-01-01T00:00',
          'to_ProactiveActionConfig_UpdatedOn': '2025-12-31T23:59',
          'orderBy': 'UpdatedOn',
          'dir': 1 // Descending
      },
      headers={
          'Authorization': 'Bearer YOUR_TOKEN'
      }
  )

  data = response.json()
  ```
</CodeGroup>

## Response

### 200

<ResponseField name="Records" type="ProactiveActionConfig[]">
  The list of ProactiveActionConfig records matching the query. See the [Get one ProactiveActionConfig](/rest-api/sys/get-proactiveactionconfigs-by-id) endpoint for the full list of properties returned for each record.
</ResponseField>

<ResponseField name="CurrentPage" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="CurrentPageSize" type="integer">
  Number of records per page.
</ResponseField>

<ResponseField name="CurrentOrderField" type="string">
  The field used for sorting.
</ResponseField>

<ResponseField name="CurrentSortDirection" type="integer">
  The sort direction (`0` = ascending, `1` = descending).
</ResponseField>

<ResponseField name="FirstItem" type="integer">
  Index of the first item on the current page.
</ResponseField>

<ResponseField name="LastItem" type="integer">
  Index of the last item on the current page.
</ResponseField>

<ResponseField name="TotalItems" type="integer">
  Total number of matching records across all pages.
</ResponseField>

<ResponseField name="TotalPages" type="integer">
  Total number of pages.
</ResponseField>

<ResponseField name="HasNextPage" type="boolean">
  Whether there is a next page of results.
</ResponseField>

<ResponseField name="HasPreviousPage" type="boolean">
  Whether there is a previous page of results.
</ResponseField>

```json Example Response theme={null}
{
  "Records": [
    {
      "BusinessId": 0,
      "CriteriaType": "",
      "Enabled": false,
      "AutoExecute": false,
      "AutoExecuteMinConfidence": 0,
      "MaxActionsPerDay": null,
      "CooldownHours": 0,
      "ChannelPreference": 0,
      "CustomPromptOverride": null,
      "FirstMessage": null,
      "SystemPrompt": null,
      "CriteriaConfiguration": null,
      "Id": 87654321,
      "UpdatedOn": "2025-01-15T10:30:00Z",
      "CreatedOn": "2025-01-10T08:00:00Z",
      "UniqueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "UpdatedBy": "admin@example.com",
      "IsNew": false,
      "SystemId": null,
      "ToStringText": "ProactiveActionConfig Example",
      "LocalizationDetails": null,
      "CustomFields": null
    }
  ],
  "CurrentPageSize": 15,
  "CurrentPage": 1,
  "CurrentOrderField": "CriteriaType",
  "CurrentSortDirection": 1,
  "FirstItem": 1,
  "HasNextPage": false,
  "HasPreviousPage": false,
  "LastItem": 1,
  "PageNumber": 1,
  "PageSize": 15,
  "TotalItems": 1,
  "TotalPages": 1
}
```