Pathway Rules

Pathway rules provide conditional overrides on top of base pathway configs. Rules let you customise episode routing based on event properties — for example, routing VIP appointment bookings to a specific team, or silencing billing episodes for certain invoice types.

Endpoints

Method	Endpoint	Description
`GET`	`/pathway-rules`	List rules
`GET`	`/pathway-rules/{id}`	Retrieve a rule
`POST`	`/pathway-rules`	Create a rule
`PATCH`	`/pathway-rules/{id}`	Update a rule
`DELETE`	`/pathway-rules/{id}`	Delete a rule

The Rule Object

{
  "id": "rule_123e4567-e89b-12d3-a456-426614174000",
  "trigger_type": "appointment.booked",
  "rule_name": "VIP bookings → urgent priority",
  "priority": 0,
  "conditions": {
    "appointment_type_ids": ["type_vip_consultation"]
  },
  "creation_mode": null,
  "inbox_visibility": null,
  "journey_type": null,
  "suggested_assignment": "usr_team_lead",
  "suggested_priority": "urgent",
  "expected_next_actor": null,
  "enabled": true,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Override fields set to null inherit from the base pathway config. Only non-null fields take effect.

How Rules are Evaluated

Rules are evaluated in priority order (lowest number first). The first matching rule wins — its non-null fields override the base config. If no rules match, the base config applies.

List Rules

GET /pathway-rules

Sorted by trigger_type ascending, then priority ascending (evaluation order).

Query Parameters

Parameter	Type	Description
`limit` / `offset`	integer	Pagination (default 20)
`trigger_type`	string	Filter by trigger type
`enabled`	string	Filter enabled/disabled
`creation_mode`	string	Filter by creation mode override
`suggested_priority`	string	Filter by suggested priority

Create a Rule

POST /pathway-rules

Supports idempotency via Idempotency-Key header.

Required Fields

Field	Type	Description
`trigger_type`	string	Which trigger this rule applies to
`rule_name`	string	Human-readable name
`priority`	integer	Evaluation order (0 = first, must be non-negative)

Optional Override Fields

All override fields are nullable — set to null to inherit from the base config:

Field	Type	Description
`conditions`	object	Condition matching (JSON object)
`creation_mode`	string	Override creation mode
`inbox_visibility`	string	Override inbox visibility
`journey_type`	string	Override journey type
`suggested_assignment`	string	Suggested assignee
`suggested_priority`	string	`low`, `medium`, `high`, `urgent`
`expected_next_actor`	string	`practice` or `patient`
`enabled`	boolean	Enable/disable this rule

⚠️

Each (trigger_type, priority) combination must be unique within your organisation. Attempting to create or update a rule with a duplicate priority returns 409 CONFLICT.

Update a Rule

PATCH /pathway-rules/{id}

All fields from the create endpoint are updatable except trigger_type (changing trigger type requires delete + create).

Delete a Rule

DELETE /pathway-rules/{id}

Permanently deletes the rule. The base config will apply to events that would have matched this rule.

Response

{
  "data": null,
  "meta": {
    "request_id": "req_abc123"
  }
}

Gaps in the priority sequence after deletion are fine — rules are evaluated by priority order, not contiguous numbering.

Related Resources

Pathway Configs - Base pathway configuration
Episodes - Episodes created by pathways

Pathway Configs Webhooks