> ## 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.

# Create ProposedAction

> Create a new ProposedAction record.

A ProposedAction is an AI-generated recommendation waiting in the operator AI Inbox, produced when one of the proactive agents spots an opportunity such as an overdue invoice, an expiring contract, a run of support tickets, a spike in one issue category or a gap in the FAQ. Each one carries a drafted message or an internal alert, a confidence score and a review deadline. Records are created by the proactive agents, never by hand, and cannot be deleted. Fields such as the drafted subject and body, the delivery channel and the review notes may be edited before the action goes out. Its lifecycle, however, is driven by the review operations: use the approve and reject commands (PROPOSEDACTION\_APPROVE, PROPOSEDACTION\_REJECT), which also deliver the message, rather than writing Status directly — setting Status by hand marks an action as handled without ever sending it. Which agents run and how they behave is configured through ProactiveActionConfig.

## 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 **`ProposedAction-Create`** role.
</Note>

## Enums

<Accordion title="eProposedActionType — ActionType values">
  | Value | Name          |
  | ----- | ------------- |
  | 1     | DraftMessage  |
  | 2     | VoiceOutreach |
  | 3     | InternalNote  |
  | 4     | TaskReminder  |
</Accordion>

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

<Accordion title="eProposedActionPriority — Priority values">
  | Value | Name     |
  | ----- | -------- |
  | 1     | Low      |
  | 2     | Medium   |
  | 3     | High     |
  | 4     | Critical |
</Accordion>

<Accordion title="eProposedActionStatus — Status values">
  | Value | Name          |
  | ----- | ------------- |
  | 1     | Pending       |
  | 2     | Approved      |
  | 3     | Rejected      |
  | 4     | Expired       |
  | 5     | AutoExecuted  |
  | 6     | Snoozed       |
  | 7     | Deferred      |
  | 8     | AwaitingReply |
</Accordion>

<Accordion title="eHelpDeskMessagePriority">
  | Value | Name     |
  | ----- | -------- |
  | 1     | Low      |
  | 2     | Normal   |
  | 3     | High     |
  | 4     | Critical |
</Accordion>

## Request Body

### Required Fields

<ParamField body="BusinessId" type="integer" required>
  ID of the location that owns this proposed action. Set from the location whose agents produced it..
</ParamField>

<ParamField body="CriteriaType" type="string" required>
  Identifier of the agent that produced this action, matching a criteria evaluator name such as DueInvoiceCriteria, ContractExpiryCriteria, SupportPatternCriteria, SupportIssueCategoryCriteria or MissingFaqCriteria. Behaviour for each is configured through ProactiveActionConfig..
</ParamField>

<ParamField body="ActionType" type="integer" required>
  What the action does once approved: DraftMessage sends a composed message to the customer, VoiceOutreach places an AI call, InternalNote raises an operator-only alert with no customer contact, TaskReminder records a follow-up. InternalNote actions have no customer target and no delivery channel..
</ParamField>

<ParamField body="Channel" type="integer" required>
  How an approved action reaches the customer: Email for an AI-tracked email conversation, Voice for an outbound AI call, CoworkerMessage for a message sent from a connected email account, HelpDesk to raise a ticket, or WhatsApp. Operators can change the channel at approval time. Ignored for InternalNote actions..
</ParamField>

<ParamField body="Confidence" type="number" required>
  AI confidence in this recommendation, on a 0.0–1.0 scale (not a percentage). When the matching ProactiveActionConfig enables auto-execution, an action at or above its AutoExecuteMinConfidence skips the review inbox..
</ParamField>

<ParamField body="Priority" type="integer" required>
  Urgency assigned by the agent that raised the action: Low, Medium, High or Critical. Drives inbox ordering and the urgency indicator; it does not change delivery behaviour..
</ParamField>

<ParamField body="Status" type="integer" required>
  Where the action sits in its lifecycle: Pending awaits review; Snoozed is hidden until its wake time; Approved has been accepted for delivery; AutoExecuted was sent without review because confidence cleared the configured threshold; Deferred is approved but waiting for the recipient's next calling window; AwaitingReply has sent a WhatsApp opt-in template and is waiting on the customer; Rejected was dismissed; Expired passed its review deadline unattended. Change it through the approve, reject and snooze operations rather than by writing this field..
</ParamField>

<ParamField body="DeferralCount" type="integer" required>
  Number of times delivery has been postponed for calling hours. Counts up from zero and helps spot actions that keep missing their window\..
</ParamField>

### Optional Fields

<ParamField body="CoworkerId" type="integer">
  ID of the customer this action targets. Empty for internal alerts and for leads that have no customer record yet..
</ParamField>

<ParamField body="AiChannelSessionId" type="integer">
  ID of the AI conversation that triggered this action. Only set for criteria that evaluate conversations, such as unanswered-question and dormant-lead detection..
</ParamField>

<ParamField body="DraftSubject" type="string">
  AI-composed subject line for the proposed message. Operators may edit it before approving; for internal alerts it doubles as the alert headline..
</ParamField>

<ParamField body="DraftBody" type="string">
  AI-composed message body, call script, or — for internal alerts — the alert text itself. Operators may edit it before approving..
</ParamField>

<ParamField body="ReviewedById" type="integer">
  ID of the operator who last reviewed this action. Empty while it is still awaiting review or when the system expired it unattended..
</ParamField>

<ParamField body="ReviewedOn" type="string">
  UTC time an operator last approved, rejected or snoozed this action..
</ParamField>

<ParamField body="ReviewNotes" type="string">
  Notes recorded when an operator approves, rejects or snoozes the action. The system also appends here when it expires an action, for example because no calling window was available..
</ParamField>

<ParamField body="ExecutedOn" type="string">
  UTC time the approved action was actually delivered or the outbound call placed. Empty while the action is still queued or deferred..
</ParamField>

<ParamField body="OutcomeSessionId" type="integer">
  ID of the AI conversation created when this action was delivered. Use it to follow the reply thread, escalated tickets and messages that came out of the outreach..
</ParamField>

<ParamField body="ExpiresOn" type="string">
  UTC review deadline, defaulting to three days after the action is created. A Pending action past this point is moved to Expired; for a Snoozed action this instead holds the wake time set by the snooze duration..
</ParamField>

<ParamField body="DeduplicationKey" type="string">
  Read-only key that prevents duplicate proposals for the same trigger, shaped as "criteria-type:\{identifier}:\{tier}" (for example "invoice:123:reminder:1"). A new proposal is suppressed while a non-expired action with the same key exists inside the criteria's cooldown window\..
</ParamField>

<ParamField body="ScheduledExecutionTime" type="string">
  UTC time a Deferred action becomes due, set automatically to the recipient's next calling window when approval lands outside permitted outbound hours..
</ParamField>

<ParamField body="DeferralReason" type="string">
  System-written explanation of why delivery was postponed, recorded when an approved action falls outside the recipient's permitted calling hours..
</ParamField>

<ParamField body="EmailAccountId" type="integer">
  ID of the connected email account used as the sender when an approved action goes out over the CoworkerMessage channel. Empty means the location's default outgoing mail settings are used and customer replies are not tracked back into the AI conversation..
</ParamField>

<ParamField body="InternalNotes" type="string">
  Internal context carried onto the help desk ticket created when a HelpDesk-channel action is approved. Visible to operators only, never to the customer..
</ParamField>

<ParamField body="HelpDeskDepartmentId" type="integer">
  ID of the help desk department the ticket is filed under when a HelpDesk-channel action is approved. Empty leaves the ticket unassigned..
</ParamField>

<ParamField body="HelpDeskPriority" type="integer">
  Priority applied to the help desk ticket created when a HelpDesk-channel action is approved (Low, Normal, High, Critical). Empty for actions on any other channel.. See `eHelpDeskMessagePriority?` enum above.
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    "https://spaces.nexudus.com/api/sys/proposedactions" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "BusinessId": 0,
      "CriteriaType": "",
      "ActionType": 0,
      "Channel": 0,
      "Confidence": 0,
      "Priority": 0,
      "Status": 0,
      "DeferralCount": 0
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://spaces.nexudus.com/api/sys/proposedactions',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        BusinessId: 0,
        CriteriaType: '',
        ActionType: 0,
        Channel: 0,
        Confidence: 0,
        Priority: 0,
        Status: 0,
        DeferralCount: 0
      })
    }
  );

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

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

  response = requests.post(
      'https://spaces.nexudus.com/api/sys/proposedactions',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'BusinessId': 0,
          'CriteriaType': '',
          'ActionType': 0,
          'Channel': 0,
          'Confidence': 0,
          'Priority': 0,
          'Status': 0,
          'DeferralCount': 0
      }
  )

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

## Response

### 200

<ResponseField name="Status" type="integer">
  HTTP status code. `200` on success.
</ResponseField>

<ResponseField name="Message" type="string">
  A human-readable message confirming the creation.
</ResponseField>

<ResponseField name="Value" type="object">
  Contains the `Id` of the newly created record.
</ResponseField>

<ResponseField name="WasSuccessful" type="boolean">
  `true` if the proposedaction was created successfully.
</ResponseField>

<ResponseField name="Errors" type="array">
  `null` on success.
</ResponseField>

```json Example Response theme={null}
{
  "Status": 200,
  "Message": "ProposedAction was successfully created.",
  "Value": {
    "Id": 87654321
  },
  "OpenInDialog": false,
  "OpenInWindow": false,
  "RedirectURL": null,
  "JavaScript": null,
  "UpdatedOn": "2025-01-15T10:30:00Z",
  "UpdatedBy": "admin@example.com",
  "Errors": null,
  "WasSuccessful": true
}
```

### 400

<ResponseField name="Message" type="string">
  A summary of the validation error(s), in the format `PropertyName: error message`.
</ResponseField>

<ResponseField name="Value" type="any">
  `null` on validation failure.
</ResponseField>

<ResponseField name="Errors" type="object[]">
  Array of validation errors.

  <Expandable>
    <ResponseField name="AttemptedValue" type="any">
      The value that was submitted for the field, or `null` if missing.
    </ResponseField>

    <ResponseField name="Message" type="string">
      The validation error message.
    </ResponseField>

    <ResponseField name="PropertyName" type="string">
      The name of the property that failed validation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="WasSuccessful" type="boolean">
  `false` when the request fails validation.
</ResponseField>

```json Example Response theme={null}
{
  "Message": "CriteriaType: is a required field",
  "Value": null,
  "Errors": [
    {
      "AttemptedValue": null,
      "Message": "is a required field",
      "PropertyName": "CriteriaType"
    }
  ],
  "WasSuccessful": false
}
```