Run Automation Manually

Overview

Trigger automated or semi-automated clinical pathway execution for a patient record. This endpoint initiates the processing workflow that evaluates pathway conditions, executes actions, and manages the patient journey through the configured pathway.

Endpoint

POST https://app.arahealth.io/api/v1/pub/records/automation

Base URL: https://app.arahealth.io Path: /api/v1/records/automation Method: POST

Authentication

This endpoint requires Bearer token authentication.

Headers

Authorization (required) - Bearer token for authentication
Content-Type (required) - Must be application/json

Contact Alto Health to obtain your authentication token. The token contains your organization, team, and user credentials.

Request Parameters

Request Body

The request body should be a JSON object with the following fields:

Field	Type	Required	Description
`recordId`	string	Yes	Unique identifier for the patient record
`pathwayType`	string	Yes	Type of pathway execution: `auto` or `semiAutomatic`
`pathwayName`	string	Conditional	Name of the pathway to execute (required for `semiAutomatic` type)

Pathway Types

auto - Fully Automated

The pathway runs automatically from start to finish without manual intervention. The system will:

Execute all pathway nodes sequentially
Evaluate conditions automatically
Complete actions without user input
Progress through the entire pathway flow

Use when: You want the system to process the record completely automatically based on extracted data and configured rules.

semiAutomatic - Semi-Automated

The pathway executes with manual checkpoints where user review or intervention is required. The system will:

Pause at designated review points
Wait for user approval or input
Allow manual override of automated decisions
Resume execution after user action

Use when: You need human oversight at critical decision points in the pathway.

When using semiAutomatic, you must provide the pathwayName parameter to specify which pathway to execute.

Code Examples

const response = await fetch('https://app.arahealth.io/api/v1/pub/records/automation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_auth_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recordId: '6924b6882ccfec0e13b8e4b9',
    pathwayType: 'semiAutomatic',
    pathwayName: 'Achilles tendon pathology and rupture'
  })
});

const data = await response.json();
console.log(data);
// { status_code: 200, message: 'success', sub_message: 'success' }

Response

Success Response

A successful automation trigger returns:

{
  "status_code": 200,
  "message": "success",
  "sub_message": "success"
}

Response Fields

Field	Type	Description
`status_code`	number	HTTP status code (200 for success)
`message`	string	High-level status message
`sub_message`	string	Additional status details

Error Responses

Invalid Request (400)

{
  "status_code": 400,
  "message": "Invalid request",
  "detail": "recordId is required"
}

Common causes:

Missing required fields (recordId, pathwayType)
Invalid recordId format
Missing pathwayName when using semiAutomatic type
Invalid pathwayType value

Unauthorized (401)

{
  "status_code": 401,
  "message": "Unauthorized",
  "detail": "Invalid or expired token"
}

Common causes:

Missing Authorization header
Invalid Bearer token
Expired authentication token

Record Not Found (404)

{
  "status_code": 404,
  "message": "Record not found",
  "detail": "No record found with the provided recordId"
}

Common causes:

Invalid recordId
Record belongs to a different organization/team
Record has been archived or deleted

Use Cases

Automatic Triage

Trigger automatic pathway execution after document upload to classify and route referrals based on urgency and specialty.

Approval Workflows

Use semi-automatic pathways for cases requiring clinical review before proceeding with automated actions.

Batch Processing

Process multiple records through the same pathway by calling this endpoint for each record in a batch.

Integration Triggers

Integrate with external systems to automatically trigger pathways when new records are created.

Example Workflow

Upload Document

Use the Document Upload endpoint to upload a patient referral document. Save the returned recordId.

Trigger Automation

Call the Run Automation Manually endpoint with the recordId to execute the clinical pathway. The pathway will automatically handle data extraction:

await fetch('https://app.arahealth.io/api/v1/pub/records/automation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recordId: savedRecordId,
    pathwayType: 'auto'
  })
});

Monitor Progress

The pathway executes asynchronously. Use webhooks or polling to monitor pathway execution status and completion.

Pathway Execution

What Happens When You Trigger Automation?

When you call this endpoint, Alto Health:

Validates the Request - Checks that the record exists and you have permission to access it
Loads the Pathway - Retrieves the configured pathway based on the type and name provided
Initializes Execution - Creates a run history record to track the pathway execution
Processes Nodes - Executes pathway nodes sequentially:
- Evaluates conditions based on extracted data
- Performs actions (notifications, status updates, etc.)
- Makes routing decisions based on business rules
Handles Wait Points - For semi-automatic pathways, pauses at designated review nodes
Completes or Pauses - Either completes the pathway or waits for manual intervention

Pathway Node Types

During execution, the pathway may include various node types:

Condition Nodes - Evaluate rules based on extracted data
Action Nodes - Perform operations like sending emails or updating status
Decision Nodes - Route the record based on evaluation results
Wait Nodes - Pause execution for manual review (semi-automatic only)

Best Practices

Validate Data Before Automation

Ensure that all required entity extraction is complete before triggering automation. Missing data may cause pathway execution to fail or make incorrect routing decisions.

// Check extraction status first
const jobStatus = await fetch(`https://app.arahealth.io/v1/jobs/${jobId}`);
const { status } = await jobStatus.json();

// Only trigger automation if extraction succeeded
if (status === 'completed') {
  await fetch('/api/v1/records/automation', {
    method: 'POST',
    body: JSON.stringify({ recordId, pathwayType: 'auto' })
  });
}

Handle Asynchronous Execution

Pathway execution happens asynchronously. Don’t expect immediate results. Use webhooks or implement polling to track completion.

// Trigger automation
const response = await fetch('/api/v1/records/automation', {
  method: 'POST',
  body: JSON.stringify({ recordId, pathwayType: 'auto' })
});

if (response.status === 200) {
  console.log('Automation started - results will be available asynchronously');
}

Use Semi-Automatic for Critical Cases

For high-stakes clinical decisions, use semiAutomatic pathways to include human oversight at critical decision points.

// High-priority case requiring review
await fetch('/api/v1/records/automation', {
  method: 'POST',
  body: JSON.stringify({
    recordId,
    pathwayType: 'semiAutomatic',
    pathwayName: 'High Priority Review Pathway'
  })
});

Verify Pathway Names

When using semi-automatic execution, ensure the pathway name exactly matches a configured pathway in your organization. Mismatched names will cause the request to fail.

Implement Error Handling

Always implement proper error handling for automation requests:

try {
  const response = await fetch('/api/v1/records/automation', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ recordId, pathwayType: 'auto' })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Automation failed: ${error.detail}`);
  }

  const result = await response.json();
  console.log('Automation triggered successfully:', result);
} catch (error) {
  console.error('Failed to trigger automation:', error);
  // Implement retry logic or alert admins
}

Document Upload

Upload patient referral documents before triggering automation

Get Job Status

Check the status of processing jobs

Webhooks

Set up webhooks to receive automation completion notifications

Need Help?

Contact Support

Email: [email protected]Include in your message:

Record ID
Pathway name (if applicable)
Error message and status code
Expected vs actual behavior

Authorizations

Authorization

string

header

required

Bearer token authentication using your Alto Health API key

Body

application/json

Automation execution request

recordId

string

required

Unique identifier for the patient record

Example:

"6924b6882ccfec0e13b8e4b9"

pathwayType

enum<string>

required

Type of pathway execution

Available options:

auto,

semiAutomatic

Example:

"semiAutomatic"

pathwayName

string

Name of the pathway to execute (required for semiAutomatic type)

Example:

"Achilles tendon pathology and rupture"

Response

Automation triggered successfully

status_code

integer

HTTP status code

Example:

200

message

string

High-level status message

Example:

"success"

sub_message

string

Additional status details

Example:

"success"

Overview

File Endpoints

Automation

Automation Use Cases

System

Run Automation Manually

Overview

Endpoint

Authentication

Headers

Request Parameters

Request Body

Pathway Types

Code Examples

Response

Success Response

Response Fields

Error Responses

Invalid Request (400)

Unauthorized (401)

Record Not Found (404)

Use Cases

Automatic Triage

Approval Workflows

Batch Processing

Integration Triggers

Example Workflow

Pathway Execution

What Happens When You Trigger Automation?

Pathway Node Types

Best Practices

Document Upload

Get Job Status

Webhooks

Need Help?

Contact Support

Authorizations

Body

Response

Overview

File Endpoints

Automation

Automation Use Cases

System

​Overview

​Endpoint

​Authentication

​Headers

​Request Parameters

​Request Body

​Pathway Types

​Code Examples

​Response

​Success Response

​Response Fields

​Error Responses

​Invalid Request (400)

​Unauthorized (401)

​Record Not Found (404)

​Use Cases

Automatic Triage

Approval Workflows

Batch Processing

Integration Triggers

​Example Workflow

​Pathway Execution

​What Happens When You Trigger Automation?

​Pathway Node Types

​Best Practices

​Related Endpoints

Document Upload

Get Job Status

Webhooks

​Need Help?

Contact Support

Authorizations

Body

Response

Overview

Endpoint

Authentication

Headers

Request Parameters

Request Body

Pathway Types

Code Examples

Response

Success Response

Response Fields

Error Responses

Invalid Request (400)

Unauthorized (401)

Record Not Found (404)

Use Cases

Example Workflow

Pathway Execution

What Happens When You Trigger Automation?

Pathway Node Types

Best Practices

Related Endpoints

Need Help?