Automations API

Overview

Manage event-driven workflow automations for organization lifecycle events.

Base Path: /v1/automations

Access Control:

Admins: Full access (create, read, update, delete, test)
Specialists: Read-only access to view automation rules
Patients/Customer Support: No access

Automation Rules Endpoints

List Automation Rules

GET /v1/automations/rules

Query Parameters:

trigger_event (optional) - Filter by trigger event
enabled (optional) - Filter by enabled status (true/false)
page (optional) - Page number (default: 1)
limit (optional) - Results per page (default: 20)

Response: 200 OK

json

{
  "data": [
    {
      "id": 1,
      "organization_id": 1,
      "name": "New Patient GDPR & Welcome",
      "description": "Require GDPR consent and send welcome email",
      "enabled": true,
      "trigger_event": "patient.onboarded",
      "trigger_config": {},
      "conditions": {},
      "actions": [
        {
          "type": "require_form",
          "form_template_id": 42,
          "blocking": true
        },
        {
          "type": "send_email",
          "template": "welcome_patient"
        }
      ],
      "execution_count": 150,
      "last_executed_at": "2025-02-14T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-02-10T15:00:00Z"
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "limit": 20
  }
}

Get Automation Rule

GET /v1/automations/rules/{id}

Response: 200 OK

json

{
  "data": {
    "id": 1,
    "organization_id": 1,
    "name": "New Patient GDPR & Welcome",
    "description": "Require GDPR consent and send welcome email to new patients",
    "enabled": true,
    "trigger_event": "patient.onboarded",
    "trigger_config": {},
    "conditions": {},
    "actions": [
      {
        "type": "require_form",
        "form_template_id": 42,
        "blocking": true,
        "description": "Privacy Policy & GDPR Consent"
      },
      {
        "type": "require_form",
        "form_template_id": 43,
        "blocking": true,
        "description": "Terms of Service"
      },
      {
        "type": "send_email",
        "template": "welcome_patient",
        "delay_minutes": 5
      }
    ],
    "execution_count": 150,
    "last_executed_at": "2025-02-14T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-02-10T15:00:00Z"
  }
}

Errors:

404 automation_rule_not_found - Rule doesn't exist

Create Automation Rule

POST /v1/automations/rules

Request:

json

{
  "name": "First Video Appointment Setup",
  "description": "Require video consent for first video appointments",
  "enabled": true,
  "trigger_event": "appointment.first_booked",
  "trigger_config": {},
  "conditions": {
    "appointment.type": "video"
  },
  "actions": [
    {
      "type": "require_form",
      "form_template_id": 50,
      "blocking": true,
      "description": "Video Recording Consent"
    },
    {
      "type": "send_email",
      "template": "first_appointment_video_guide"
    }
  ]
}

Response: 201 Created

json

{
  "data": {
    "id": 5,
    "organization_id": 1,
    "name": "First Video Appointment Setup",
    "enabled": true,
    "trigger_event": "appointment.first_booked",
    "conditions": {
      "appointment.type": "video"
    },
    "actions": [
      {
        "type": "require_form",
        "form_template_id": 50,
        "blocking": true
      },
      {
        "type": "send_email",
        "template": "first_appointment_video_guide"
      }
    ],
    "execution_count": 0,
    "last_executed_at": null,
    "created_at": "2025-02-15T10:00:00Z",
    "updated_at": "2025-02-15T10:00:00Z"
  }
}

Errors:

400 validation_error - Invalid trigger_event or action type
403 forbidden - User is not an admin

Update Automation Rule

PUT /v1/automations/rules/{id}

Request:

json

{
  "name": "Updated Rule Name",
  "enabled": false,
  "actions": [
    {
      "type": "send_email",
      "template": "new_template"
    }
  ]
}

All fields are optional. Only provided fields are updated.

Response: 200 OK

json

{
  "data": {
    "id": 5,
    "name": "Updated Rule Name",
    "enabled": false,
    "updated_at": "2025-02-15T11:00:00Z"
  }
}

Errors:

404 automation_rule_not_found
403 forbidden

Delete Automation Rule

DELETE /v1/automations/rules/{id}

Response: 204 No Content

Errors:

404 automation_rule_not_found
403 forbidden

Test Automation Rule

Simulate what would happen if this rule executed for a given entity.

POST /v1/automations/rules/{id}/test

Request:

json

{
  "trigger_entity_type": "patient",
  "trigger_entity_id": 100
}

Response: 200 OK

json

{
  "data": {
    "would_execute": true,
    "conditions_matched": true,
    "actions_preview": [
      {
        "type": "require_form",
        "form_template_id": 42,
        "would_create_form": true,
        "blocking": true
      },
      {
        "type": "send_email",
        "template": "welcome_patient",
        "would_send_to": "[email protected]"
      }
    ]
  }
}

Errors:

404 automation_rule_not_found
404 entity_not_found - Test entity doesn't exist

Automation Executions Endpoints

List Automation Executions

View execution history for all or specific automation rules.

GET /v1/automations/executions

Query Parameters:

automation_rule_id (optional) - Filter by rule
status (optional) - Filter by status (success, partial_failure, failure, skipped)
trigger_event (optional) - Filter by trigger event
from_date (optional) - ISO 8601 date (e.g., 2025-02-01)
to_date (optional) - ISO 8601 date
page (optional) - Page number (default: 1)
limit (optional) - Results per page (default: 20, max: 100)

Response: 200 OK

json

{
  "data": [
    {
      "id": 1000,
      "organization_id": 1,
      "automation_rule_id": 1,
      "automation_rule_name": "New Patient GDPR & Welcome",
      "trigger_event": "patient.onboarded",
      "trigger_entity_type": "patient",
      "trigger_entity_id": 100,
      "status": "success",
      "actions_executed": [
        {
          "action": "require_form",
          "status": "success",
          "form_id": 500
        },
        {
          "action": "require_form",
          "status": "success",
          "form_id": 501
        },
        {
          "action": "send_email",
          "status": "success",
          "email_id": "msg_abc123"
        }
      ],
      "error_message": null,
      "executed_at": "2025-02-15T10:05:00Z"
    },
    {
      "id": 999,
      "automation_rule_id": 2,
      "automation_rule_name": "Pre-Appointment Reminder",
      "trigger_event": "appointment.before_start",
      "trigger_entity_type": "appointment",
      "trigger_entity_id": 50,
      "status": "partial_failure",
      "actions_executed": [
        {
          "action": "send_sms",
          "status": "success",
          "sms_id": "sms_xyz789"
        },
        {
          "action": "send_email",
          "status": "failure",
          "error": "SMTP connection timeout"
        }
      ],
      "error_message": "Email sending failed",
      "executed_at": "2025-02-14T10:00:00Z"
    }
  ],
  "meta": {
    "total": 5000,
    "page": 1,
    "limit": 20
  }
}

Get Automation Execution

GET /v1/automations/executions/{id}

Response: 200 OK

json

{
  "data": {
    "id": 1000,
    "organization_id": 1,
    "automation_rule_id": 1,
    "automation_rule_name": "New Patient GDPR & Welcome",
    "trigger_event": "patient.onboarded",
    "trigger_entity_type": "patient",
    "trigger_entity_id": 100,
    "status": "success",
    "actions_executed": [
      {
        "action": "require_form",
        "type": "require_form",
        "form_template_id": 42,
        "status": "success",
        "form_id": 500,
        "duration_ms": 120
      },
      {
        "action": "send_email",
        "type": "send_email",
        "template": "welcome_patient",
        "status": "success",
        "email_id": "msg_abc123",
        "duration_ms": 350
      }
    ],
    "error_message": null,
    "executed_at": "2025-02-15T10:05:00Z"
  }
}

Errors:

404 execution_not_found

Trigger Catalog Endpoint

Get list of all available trigger events with descriptions.

GET /v1/automations/triggers

Response: 200 OK

json

{
  "data": [
    {
      "event": "patient.onboarded",
      "category": "patient_lifecycle",
      "description": "New patient registered in the system",
      "entity_type": "patient",
      "config_schema": null
    },
    {
      "event": "patient.first_login",
      "category": "patient_lifecycle",
      "description": "Patient logs in for the first time",
      "entity_type": "patient",
      "config_schema": null
    },
    {
      "event": "appointment.before_start",
      "category": "appointment_lifecycle",
      "description": "Fires X hours/days before appointment starts",
      "entity_type": "appointment",
      "config_schema": {
        "hours_before": {
          "type": "integer",
          "description": "Hours before appointment to trigger",
          "default": 24,
          "min": 1,
          "max": 168
        }
      }
    }
  ]
}

Action Types Catalog Endpoint

Get list of all available action types with schemas.

GET /v1/automations/actions

Response: 200 OK

json

{
  "data": [
    {
      "type": "require_form",
      "category": "data_collection",
      "description": "Create form instance and block access until signed",
      "config_schema": {
        "form_template_id": {
          "type": "integer",
          "required": true,
          "description": "Form template to instantiate"
        },
        "blocking": {
          "type": "boolean",
          "required": true,
          "description": "Block booking/access until form signed"
        },
        "description": {
          "type": "string",
          "required": false,
          "description": "Human-readable description"
        }
      }
    },
    {
      "type": "send_email",
      "category": "communication",
      "description": "Send transactional email to patient",
      "config_schema": {
        "template": {
          "type": "string",
          "required": true,
          "description": "Email template ID"
        },
        "delay_minutes": {
          "type": "integer",
          "required": false,
          "description": "Delay before sending (minutes)",
          "default": 0
        }
      }
    },
    {
      "type": "update_segment",
      "category": "data_management",
      "description": "Add or remove patient from segment",
      "config_schema": {
        "segment_id": {
          "type": "integer",
          "required": true,
          "description": "Segment to update"
        },
        "action": {
          "type": "string",
          "required": true,
          "enum": ["add", "remove"],
          "description": "Add or remove from segment"
        }
      }
    }
  ]
}

Note: For external system integrations (webhooks, Make.com, Zapier), use the Webhooks feature instead. Automations focus on internal workflows only.

Access Control Matrix

Endpoint	Admin	Specialist	Patient	Support
`GET /rules`	✅	✅ (read-only)	❌	❌
`GET /rules/{id}`	✅	✅ (read-only)	❌	❌
`POST /rules`	✅	❌	❌	❌
`PUT /rules/{id}`	✅	❌	❌	❌
`DELETE /rules/{id}`	✅	❌	❌	❌
`POST /rules/{id}/test`	✅	❌	❌	❌
`GET /executions`	✅	✅ (read-only)	❌	❌
`GET /executions/{id}`	✅	✅ (read-only)	❌	❌
`GET /triggers`	✅	✅	❌	❌
`GET /actions`	✅	✅	❌	❌

Automations API ​

Overview ​

Automation Rules Endpoints ​

List Automation Rules ​

Get Automation Rule ​

Create Automation Rule ​

Update Automation Rule ​

Delete Automation Rule ​

Test Automation Rule ​

Automation Executions Endpoints ​

List Automation Executions ​

Get Automation Execution ​

Trigger Catalog Endpoint ​

Action Types Catalog Endpoint ​

Access Control Matrix ​

Automations API

Overview

Automation Rules Endpoints

List Automation Rules

Get Automation Rule

Create Automation Rule

Update Automation Rule

Delete Automation Rule

Test Automation Rule

Automation Executions Endpoints

List Automation Executions

Get Automation Execution

Trigger Catalog Endpoint

Action Types Catalog Endpoint

Access Control Matrix