API Reference

Workflows

Workflow triggering and execution monitoring endpoints

List available workflow types, trigger executions, and monitor their progress. Also includes application-specific convenience endpoints.

List Workflow Types

GET /api/public/v1/workflows

Returns all active workflow definitions available for your organization.

Required Scope: workflows:read

Parameter	Type	Description
entity_type	string	Filter by entity type (e.g., deal, application, merchant)
category	string	Filter by category

Response:

{
  "data": [
    {
      "id": "wf_abc123",
      "name": "Deal Onboarding",
      "description": "Automated deal onboarding with compliance checks",
      "icon": "briefcase",
      "category": "onboarding",
      "entityType": "deal",
      "triggerType": "manual",
      "status": "active",
      "isActive": true,
      "version": 3
    }
  ],
  "total": 5
}

---

Get Workflow Type

GET /api/public/v1/workflows/{id}

Returns full details of a workflow type including trigger conditions and configuration.

Required Scope: workflows:read

Response:

{
  "id": "wf_abc123",
  "name": "Deal Onboarding",
  "description": "Automated deal onboarding with compliance checks",
  "icon": "briefcase",
  "category": "onboarding",
  "entityType": "deal",
  "triggerType": "manual",
  "status": "active",
  "isActive": true,
  "version": 3,
  "triggerConditions": { ... },
  "onFailure": "pause",
  "maxRetries": 3,
  "nodeCount": 8
}

---

Trigger Workflow

POST /api/public/v1/workflows/trigger

Trigger a workflow execution for a specific entity.

Required Scope: workflows:trigger

Request Body

Field	Type	Required	Description
workflowType	string	Yes	Workflow definition ID
entityType	string	Yes	Must match the workflow’s entity type
entityId	string	Yes	ID of the entity to run the workflow on

Response 202 Accepted

{
  "executionId": "exec_xyz789",
  "workflowId": "wf_abc123",
  "workflowName": "Deal Onboarding",
  "entityType": "deal",
  "entityId": "deal_456",
  "status": "pending",
  "message": "Workflow \"Deal Onboarding\" triggered"
}

cURL

curl -X POST https://api.smartmca.com/api/public/v1/workflows/trigger \
  -H "Authorization: Bearer smca_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workflowType": "wf_abc123",
    "entityType": "deal",
    "entityId": "deal_456"
  }'

JavaScript

const res = await fetch('https://api.smartmca.com/api/public/v1/workflows/trigger', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer smca_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workflowType: 'wf_abc123',
    entityType: 'deal',
    entityId: 'deal_456',
  }),
});
const result = await res.json();
// result.executionId → use to poll status

Python

import requests

resp = requests.post(
    'https://api.smartmca.com/api/public/v1/workflows/trigger',
    headers={'Authorization': 'Bearer smca_live_...'},
    json={
        'workflowType': 'wf_abc123',
        'entityType': 'deal',
        'entityId': 'deal_456',
    },
)
execution_id = resp.json()['executionId']

---

List Executions

GET /api/public/v1/workflows/executions

Required Scope: workflows:read

Parameter	Type	Default	Description
workflow_type	string	—	Filter by workflow definition ID
entity_type	string	—	Filter by entity type
entity_id	string	—	Filter by entity ID
status	string	—	Filter: pending, running, completed, failed, cancelled
page	number	1	Page number
limit	number	20	Items per page (max 100)
sort_by	string	startedAt	Sort field
sort_order	string	desc	asc or desc

---

Get Execution

GET /api/public/v1/workflows/executions/{executionId}

Returns full execution details including node-level status and results.

Required Scope: workflows:read

---

Application Convenience Endpoints

These endpoints provide shortcuts for common application workflow operations.

Change Application Status

POST /api/public/v1/applications/{applicationId}/change-status

Required Scope: workflows:trigger

Advance Application Stage

POST /api/public/v1/applications/{applicationId}/advance-stage

Required Scope: workflows:trigger

Assign Underwriter

POST /api/public/v1/applications/{applicationId}/assign-underwriter

Required Scope: underwriting:trigger

---

Scopes

Action	Scope
List workflows, executions, get details	workflows:read
Trigger workflows, change status, advance stage	workflows:trigger
Assign underwriter	underwriting:trigger