API call to initiate a workflow

API Endpoint

Method: POST

Endpoint Structure:

https://<regional-base-url>/v2/api/bot/:botId/app/:appIdOrIdentifier/external/init

Path Parameters

Parameter	Type	Description
`botId`	String	The Bot ID of your Leena AI instance. Found in the dashboard URL.
`appIdOrIdentifier`	String	Either the App ID (MongoDB ObjectId) OR the App Identifier (custom string). The system automatically detects which format you're using.

How to Find Path Parameters

Finding botId:

From your dashboard URL, extract the Bot ID:

https://dashboard.leena.ai/bots/{botId}/workflowsV2/apps/...
                                ↑↑↑↑↑↑
                              This is your botId

Finding appId or appIdentifier:

Option 1 - App ID from dashboard URL:

https://dashboard.leena.ai/bots/{botId}/workflowsV2/apps/{appId}
                                                         ↑↑↑↑↑↑
                                                    This is your appId

Option 2 - App Identifier from application settings:

The custom identifier you configured in the "App Identifier" field when creating the application (e.g., leave-request-app).

Regional Base URLs

Region	Base URL
AWS India (Default)	`workflows-api.leena.ai`
AWS North Virginia	`us-east-1-api-workflows.leena.ai`
AWS Europe	`eu-west-1-api-workflows.leena.ai`
AWS Singapore	`ap-southeast-1-api-workflows.leena.ai`
AWS Qatar	`qatarcentral-1-api-workflows.leena.ai`
AWS UAE	`me-central-1-api-workflows.leena.ai`

Complete Example URLs

Using App ID (ObjectId) - India Region:

https://workflows-api.leena.ai/v2/api/bot/64f1a2b3c4d5e6f7a8b9c0d1/app/507f1f77bcf86cd799439011/external/init

Using App Identifier - North Virginia Region:

https://us-east-1-api-workflows.leena.ai/v2/api/bot/64f1a2b3c4d5e6f7a8b9c0d1/app/leave-request-app/external/init

Authentication

The following authentication methods are supported:

X-APP-SECRET — Include the X-APP-SECRET header with your application secret
Bot User Token — Use a valid bot user token

To initiate a workflow via REST API, use the Leena AI connector (webhook/REST API) with auth type = Leena AI x-app-secret.

Optional Headers

Header	Type	Description
`system-admin`	Boolean	Set to `true` to bypass user-specific access checks (for trusted system-to-system integrations)

Request Body

Key	Type	Required	Description
`userId`	String	Yes	The Employee ID/User ID of the workflow initiator. This user becomes the "Initiator" of the request.
`formData`	Object	No	Key-value pairs for form fields mapped under the "Initiator Input" node. Keys are the field IDs defined in your form.
`formDataLabel`	Object	No	Handles dropdown field values. Contains the field ID as key, with `label` and `value` properties for each option.
`thirdPartyReferenceId`	String	No	An optional reference ID from your external system for tracking purposes.
`userObj`	Object	No	Override initiator details with custom user information (see below).

userObj Properties (Optional)

Property	Type	Description
`userId`	String	Override the initiator's user ID
`displayName`	String	Display name for the initiator
`email`	String	Email address
`employeeId`	String	Employee ID
`name`	String	Full name

Request Body Examples

Basic Example

{
  "userId": "EMP-001028",
  "formData": {
    "name": "John Doe",
    "email": "[email protected]",
    "numberOfDays": 5
  }
}

Example with Dropdown Fields

{
  "userId": "EMP-001028",
  "formData": {
    "name": "John Doe",
    "email": "[email protected]",
    "numberOfDays": 5
  },
  "formDataLabel": {
    "leaveType": {
      "label": "Sick Leave",
      "value": "SL"
    },
    "department": {
      "label": "Engineering",
      "value": "ENG"
    }
  }
}

Example with Multi-Select Dropdown

{
  "userId": "EMP-001028",
  "formData": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "formDataLabel": {
    "selectedCategories": [
      {
        "label": "Category A",
        "value": "CAT_A"
      },
      {
        "label": "Category B",
        "value": "CAT_B"
      }
    ]
  }
}

Example with User Object Override

{
  "userId": "EMP-001028",
  "formData": {
    "requestDetails": "Equipment request for new laptop"
  },
  "userObj": {
    "userId": "EMP-001028",
    "displayName": "John Doe",
    "email": "[email protected]"
  },
  "thirdPartyReferenceId": "EXT-REF-12345"
}

Response

Success Response

{
  "success": true,
  "workflowItemId": "507f1f77bcf86cd799439011",
  "referenceId": "64abc123def456789",
  "data": {}
}

Field	Description
`success`	Boolean indicating if the workflow was initiated successfully
`workflowItemId`	The unique ID of the created workflow item
`referenceId`	Reference ID for the workflow execution
`data`	Custom response data based on the JSON Response Template configured on the Trigger node

Error Response

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Prerequisites

Before initiating a workflow via API, ensure:

The workflow application is published and active
The trigger node has "Allow execution via webhook" enabled
The userId specified exists in the system and has appropriate audience permissions
All required form fields are included in the formData object