Starting Workflows - Sample Healthcare

Besides starting a workflow from the Sample Dashboard, you can also start a workflow via API.

Prerequisites

To start a workflow, you will require two things

A SampleHC API key (see Authentication)
The slug (unique identifier) of the workflow you want to start

To find a workflow slug, from the workflow page, click the Edit button at the top right.

On the edit page, next to the title of the workflow (e.g., Sample Workflow Template), you will see the slug (e.g., sample-workflow-template).

Making a request

Below are examples of how to start a workflow with different types of request bodies. Remember to replace YOUR_API_KEY with your actual API key and <my-workflow-slug> with the slug of your workflow.

Using `application/json`

If you want to send data as a JSON object, use the Content-Type: application/json header. The body should be a JSON object, optionally containing a startData field.

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"startData": {"name": "First Workflow Instance", "priority": "high"}}' \
  https://api.samplehc.com/api/v2/workflows/<my-workflow-slug>/start

Using `multipart/form-data`

If you need to include files or send data as form fields, use multipart/form-data. curl will set the Content-Type header automatically when you use the -F option. Any form fields you send will be collected into the startData. If you send files, they will be processed and their resulting identifiers or content will also be part of startData.

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'customerName=Acme Corp' \
  -F 'orderId=12345' \
  -F 'attachmentFile=@/path/to/your/invoice.pdf' \
  https://api.samplehc.com/api/v2/workflows/<my-workflow-slug>/start

Start Data Schema

The start_data_schema field in a workflow definition allows you to specify the expected structure and validation rules for data sent when starting a workflow. This schema follows the JSON Schema specification and helps ensure data quality and provides clear documentation of expected inputs.

Simple Schema Examples

Here are some basic examples of start_data_schema definitions:

Basic Form Fields

from workflows_py.workflow import Workflow

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "patient_name": {
                "type": "string",
                "description": "Full name of the patient",
            },
            "patient_age": {
                "type": "integer",
                "description": "Age in years",
                "minimum": 0,
                "maximum": 150,
            },
            "visit_date": {
                "type": "string",
                "description": "Date of visit in YYYY-MM-DD format",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            },
            "is_emergency": {
                "type": "boolean",
                "description": "Whether this is an emergency visit",
            },
        },
        "required": ["patient_name", "visit_date"],
    },
)

File Upload Schema

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "document": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "File metadata ID",
                    },
                    "fileName": {
                        "type": "string",
                        "description": "Original file name",
                    },
                },
                "description": "Patient enrollment document",
                "x-formFieldType": "file",
                "x-formFieldOrder": 1,
                "x-formFieldLabel": "Upload Document",
            },
        },
        "required": ["document"],
    },
)

Complex Schema Examples

Medical Workflow with Nested Objects

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "document": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "File metadata ID",
                    },
                    "fileName": {
                        "type": "string",
                        "description": "File name",
                    },
                },
                "description": "The enrollment form for the patient",
                "x-formFieldType": "file",
                "x-formFieldOrder": 1,
                "x-formFieldLabel": "Enrollment Form",
            },
            "patient_id": {
                "type": "string",
                "description": "Patient ID in format P followed by 6 digits",
                "pattern": "^P\\d{6}$",
                "x-formFieldOrder": 2,
                "x-formFieldLabel": "Patient ID",
            },
            "visit_date": {
                "type": "string",
                "description": "Date of visit in YYYY-MM-DD format",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            },
            "patient_age": {
                "type": "integer",
                "description": "Patient's age in years",
                "minimum": 0,
                "maximum": 150,
            },
            "visit_cost": {
                "type": "number",
                "description": "Cost of the visit in dollars",
                "minimum": 0,
            },
            "is_emergency": {
                "type": "boolean",
                "description": "Whether this is an emergency visit",
            },
            "visit_type": {
                "type": "string",
                "enum": ["routine", "follow-up", "emergency", "consultation"],
                "description": "Type of medical visit",
            },
            "symptoms": {
                "type": "array",
                "description": "List of symptoms reported by patient",
                "items": {"type": "string"},
                "minItems": 1,
            },
            "insurance_info": {
                "type": "object",
                "description": "Patient's insurance information",
                "properties": {
                    "provider": {
                        "type": "string",
                        "description": "Insurance provider name",
                    },
                    "policy_number": {
                        "type": "string",
                        "description": "Insurance policy number",
                    },
                    "copay": {
                        "type": "number",
                        "description": "Copay amount",
                        "minimum": 0,
                    },
                    "coverage_details": {
                        "type": "object",
                        "description": "Detailed coverage information",
                        "properties": {
                            "deductible": {
                                "type": "number",
                                "description": "Annual deductible amount",
                            },
                            "coverage_percentage": {
                                "type": "integer",
                                "description": "Percentage of coverage",
                                "minimum": 0,
                                "maximum": 100,
                            },
                        },
                        "required": ["deductible"],
                    },
                },
                "required": ["provider", "policy_number"],
            },
            "email": {
                "type": "string",
                "format": "email",
                "description": "Patient's email address",
            },
            "phone": {
                "type": "string",
                "pattern": "^\\+?[1-9]\\d{1,14}$",
                "description": "Patient's phone number in international format",
            },
        },
        "required": ["patient_id", "visit_date", "document"],
    },
)

Business Process Schema with Arrays and Enums

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "company_info": {
                "type": "object",
                "description": "Company registration details",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Legal company name",
                        "minLength": 2,
                        "maxLength": 100,
                    },
                    "industry": {
                        "type": "string",
                        "enum": [
                            "healthcare",
                            "finance",
                            "technology",
                            "manufacturing",
                            "retail",
                            "other"
                        ],
                        "description": "Primary industry sector",
                    },
                    "employees": {
                        "type": "array",
                        "description": "List of key employees",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "description": "Employee full name",
                                },
                                "position": {
                                    "type": "string",
                                    "description": "Job title",
                                },
                                "email": {
                                    "type": "string",
                                    "format": "email",
                                    "description": "Work email address",
                                },
                                "is_key_personnel": {
                                    "type": "boolean",
                                    "description": "Whether this is key personnel",
                                },
                            },
                            "required": ["name", "position", "email"],
                        },
                        "minItems": 1,
                        "maxItems": 50,
                    },
                },
                "required": ["name", "industry"],
            },
            "documents": {
                "type": "array",
                "description": "Required business documents",
                "items": {
                    "type": "object",
                    "properties": {
                        "id": {
                            "type": "string",
                            "description": "Document metadata ID",
                        },
                        "fileName": {
                            "type": "string",
                            "description": "Original filename",
                        },
                        "document_type": {
                            "type": "string",
                            "enum": [
                                "articles_of_incorporation",
                                "tax_id_verification",
                                "operating_agreement",
                                "other"
                            ],
                            "description": "Type of business document",
                        },
                    },
                    "required": ["id", "fileName", "document_type"],
                },
                "minItems": 1,
            },
            "annual_revenue": {
                "type": "number",
                "description": "Estimated annual revenue in USD",
                "minimum": 0,
                "maximum": 1000000000,
            },
            "setup_date": {
                "type": "string",
                "format": "date",
                "description": "When the company was established",
            },
        },
        "required": ["company_info", "documents"],
    },
)

Custom Form Field Extensions

Sample supports custom extensions to enhance form generation:

x-formFieldType: Specifies the UI component type (e.g., “file”, “date”, “select”)
x-formFieldLabel: Custom label for the form field
x-formFieldOrder: Controls the order of fields in generated forms
x-formFieldPlaceholder: Placeholder text for input fields

Schema Validation Benefits

Using start_data_schema provides several advantages:

Data Validation: Ensures incoming data meets your requirements before workflow execution
Documentation: Serves as clear documentation of expected workflow inputs
Automatic form creation: Start data automatically creates a form so there’s no additional workflow updates needed

​Prerequisites

​Making a request

​Using application/json

​Using multipart/form-data

​Start Data Schema

​Simple Schema Examples

​Basic Form Fields

​File Upload Schema

​Complex Schema Examples

​Medical Workflow with Nested Objects

​Business Process Schema with Arrays and Enums

​Custom Form Field Extensions

​Schema Validation Benefits