Skip to main content
POST
/
organization
/
rules
Create a new ruleset
curl --request POST \
  --url https://api.getfernand.com/organization/rules \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "Auto-assign incoming messages",
  "trigger": "messages.incoming",
  "actions": [
    {
      "name": "conversation.assign",
      "data": {
        "agent_id": 123
      }
    }
  ]
}
'
{
  "id": 123,
  "name": "Auto-close spam conversations",
  "status": "LIVE",
  "priority": 0,
  "stop": false,
  "trigger_name": "messages.incoming",
  "created": "2025-01-21T10:30:00Z",
  "applied_count": 42,
  "description": "Automatically closes conversations marked as spam",
  "trigger_data": "2 hours",
  "filters": [
    {
      "field": "conversation.status",
      "operator": "equals",
      "value": "OPENED"
    }
  ],
  "actions": [
    {
      "name": "conversation.close",
      "data": {}
    }
  ],
  "last_applied_at": "2025-01-21T15:45:30Z"
}
Creates a new automation ruleset with specified trigger conditions, filters, and actions. The ruleset can be created in either LIVE or PAUSED status. When a priority is specified, all existing rules at or below that priority are shifted down. For time-based triggers (time.unanswered_by_client, time.unanswered_by_team), matching conversations are automatically excluded from future processing. Validates that the trigger exists, filters are valid for the trigger type, and actions are properly configured.

Authorizations

​
X-API-Key
string
header
required

Authenticate your account by including your secret key in API requests. You can manage your API keys in the Dashboard.

Authentication to the API is performed by using the HTTP Header X-API-Key.

Body

application/json
​
name
string
required

Name of the ruleset (required).

Maximum string length: 250
Example:

"Auto-assign incoming messages"

​
trigger
string
required

Event that triggers this rule (required). Must be one of: messages.new_conversation, messages.incoming, messages.response, messages.delivery_failure, messages.spam, messages.note, status.closed, status.opened, status.snoozed, status.unsnoozed, teammates.assigned, teammate.mentioned, time.unanswered_by_client, time.unanswered_by_team, tickets.ticket_done

Maximum string length: 50
Example:

"messages.incoming"

​
actions
object[]
required

Array of actions to execute when rule matches (required). Must contain at least one action.

Example:
[
  {
    "name": "conversation.assign",
    "data": { "agent_id": 123 }
  }
]
​
trigger_data
string

Additional data for the trigger (optional, required for certain triggers):

  • For "teammates.assigned" or "teammate.mentioned": "no_one", "anyone", or an Agent ID
  • For "time.*" triggers: duration and period in format "{duration} {period}" (e.g., "2 hours", "3 days")
Example:

"anyone"

​
filters
object[]

Array of filter conditions (optional). Filters determine when the rule should execute based on entity properties.

Example:
[
  {
    "field": "conversation.status",
    "operator": "equals",
    "value": "OPENED"
  }
]
​
status
enum<string>

Initial status of the ruleset (optional, defaults to LIVE).

Available options:
PAUSED,
LIVE
Example:

"LIVE"

​
stop
boolean

If true, stops processing subsequent rules when this rule matches (optional, defaults to false).

Example:

false

​
priority
integer

Priority order for rule execution (optional). If not specified, rule is added at the end. Lower numbers execute first.

Example:

0

Response

Ruleset created successfully.

​
id
integer<int32>
required

Unique identifier for the ruleset

​
name
string
required

Name of the ruleset

Maximum string length: 250
Example:

"Auto-close spam conversations"

​
status
enum<string>
required

Current status of the ruleset

Available options:
PAUSED,
LIVE
Example:

"LIVE"

​
priority
integer<int16>
required

Priority order for rule execution (lower numbers execute first)

Example:

0

​
stop
boolean
required

If true, stops processing subsequent rules when this rule matches

Example:

false

​
trigger_name
string
required

Event that triggers this rule. Accepted triggers:

  • messages.new_conversation
  • messages.incoming
  • messages.response
  • messages.delivery_failure
  • messages.spam
  • messages.note
  • status.closed
  • status.opened
  • status.snoozed
  • status.unsnoozed
  • teammates.assigned
  • teammate.mentioned
  • time.unanswered_by_client
  • time.unanswered_by_team
  • tickets.ticket_done
Maximum string length: 50
Example:

"messages.incoming"

​
created
string<date-time>
required

Timestamp when the ruleset was created (UTC)

Example:

"2025-01-21T10:30:00Z"

​
applied_count
integer<int32>
required

Number of times this rule has been successfully applied

Example:

42

​
description
string | null

Optional description of what the ruleset does

Maximum string length: 500
Example:

"Automatically closes conversations marked as spam"

​
trigger_data
string | null

Additional data for the trigger (required for certain triggers):

  • For "teammates.assigned" or "teammate.mentioned": "no_one", "anyone", or an Agent ID
  • For "time.*" triggers: duration and period in format "{duration} {period}" (e.g., "2 hours", "3 days")
Maximum string length: 250
Example:

"2 hours"

​
filters
object[] | null

Array of filter conditions that must be met for the rule to execute. Each filter contains conditions to match against the entity.

Example:
[
  {
    "field": "conversation.status",
    "operator": "equals",
    "value": "OPENED"
  }
]
​
actions
object[]

Array of actions to execute when the rule matches. Each action has a name and optional data.

Example:
[
  { "name": "conversation.close", "data": {} }
]
​
last_applied_at
string<date-time> | null

Timestamp when the rule was last applied (UTC)

Example:

"2025-01-21T15:45:30Z"