Workflows API

This API allows managing workflows in the system. It provides endpoints to create, read, update, and delete workflows, as well as to execute them.

The Workflow Object

The Workflow object represents a workflow in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "executionMode": "sync",
  "alias": "loan-approval",
  "version": "1.0",
  "label": "Loan Approval",
  "type": "evaluation",
  "description": "Workflow for loan approval",
  "context": "loans",
  "inputSchema": "...",
  "jsonSchema": "...",
  "uiSchema": "...",
  "flowDefinition": {},
  "batchFlowDefinition": {},
  "initialData": "...",
  "schedule": {
    "cron": "0 9 * * *",
    "utcDeltaHours": -3
  },
  "scheduleBatch": {
    "cron": "0 0 * * *",
    "utcDeltaHours": -3,
    "executionSettings": {
      "maxExecutionsPerSecond": 1,
      "maxConcurrentDispatches": 1,
      "maxItemExecutionRuns": 2
    }
  },
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-02T00:00:00Z",
  "useHighMemory": false
}

Attributes

Attribute	Description	Type
id	Unique identifier of the workflow	String
executionMode	Execution mode (sync or async)	String
alias	Alias of the workflow	String
version	Version of the workflow	String
label	Label or name of the workflow	String
type	Type of workflow (evaluation, contact, action)	String
description	Description of the workflow	String
context	Context of the workflow	String
inputSchema	Input schema of the workflow	String
jsonSchema	JSON schema of the workflow	String
uiSchema	UI schema of the workflow	String
flowDefinition	Workflow definition	Object
batchFlowDefinition	Workflow definition for batch executions	Object
initialData	Initial data of the workflow	String
schedule	Workflow schedule	Object
scheduleBatch	Workflow schedule for batch execution	Object
createdAt	Creation date and time	String (ISO 8601)
updatedAt	Last update date and time	String (ISO 8601)
useHighMemory	Indicates if the workflow requires running in a high resource environment	Boolean

Available Operations

Create a New Workflow

Creates a new workflow in the system.

POST /v1/workflows

Input Parameters

Parameter	Description	Type	Required
label	Label or name of the workflow	String	No
alias	Alias of the workflow	String	Yes
type	Type of workflow	String	No
version	Version of the workflow	String	Yes
executionMode	Execution mode	String	No
description	Description of the workflow	String	No
inputSchema	Input schema of the workflow	String	No
jsonSchema	JSON schema of the workflow	String	No
uiSchema	UI schema of the workflow	String	No
initialData	Initial data of the workflow	String	No
flowDefinition	Workflow definition	Object	No
batchFlowDefinition	Workflow definition for batch executions	Object	No
context	Context of the workflow	String	No
useHighMemory	Indicates if the workflow requires running in a high memory environment	Boolean	No

Request Example

{
  "label": "Loan Approval",
  "alias": "loan-approval",
  "type": "evaluation",
  "version": "1.0",
  "description": "Workflow for loan approval",
  "flowDefinition": {},
  "batchFlowDefinition": {},
  "context": "loans"
}

Successful Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Update a Workflow

Updates an existing workflow.

PATCH /v1/workflows/:workflow_id

Path Parameters

Parameter	Description
workflow_id	ID of the workflow to update

Input Parameters

Same as for creation, all optional.

Request Example

{
  "label": "Loan Approval (Updated)",
  "description": "Updated workflow for loan approval"
}

Successful Response

Returns the updated Workflow object.

Delete a Workflow

Deletes a workflow from the system.

DELETE /v1/workflows/:workflow_id

Path Parameters

Parameter	Description
workflow_id	ID of the workflow to delete

Successful Response

Status code 204 (No Content) if the deletion was successful.

Get a Workflow

Retrieves information of a specific workflow.

GET /v1/workflows/:workflow_id

Path Parameters

Parameter	Description
workflow_id	ID of the workflow to retrieve

Successful Response

Returns the complete Workflow object.

List Workflows

Retrieves a paginated list of workflows with filtering and sorting options.

GET /v1/workflows

Query Parameters

Parameter	Description	Type
alias	Filter by alias	String
version	Filter by version	String
type	Filter by type	String
search	Text to search	String
page	Page number	Integer
per-page	Items per page	Integer
sort-by	Field to sort by	String
sort-direction	Sorting direction (asc or desc)	String
context	Filter by context	String

Successful Response

Returns a paginated list of Workflow objects.

Execute a Workflow

Executes a specific workflow.

POST /v1/workflows/:workflow_id/execute

Path Parameters

Parameter	Description
workflow_id	ID of the workflow to execute

Input Parameters

A JSON object with the input data for the workflow.

Headers

Header	Description
x-batch-id	Batch ID for batch executions
x-tags	Tags for the execution, comma-separated
x-execution-mode	Execution mode (sync or async)

Request Example

{
  "loanAmount": 50000,
  "creditScore": 750
}

Successful Response

Returns an ExecutionOutput object.

Execute a Workflow in Batch

Executes a specific workflow for all items in a batch.

POST /v1/workflows/:workflow_id/execute-batch

Path Parameters

Parameter	Description
workflow_id	ID of the workflow to execute in batch

Input Parameters

Parameter	Description
label	Short label for the batch
description	Details about the batch
workflowInput	JSON with fields items, rawPackageIds, and customInput
attachmentFileNames	One or up to 5 file names that were uploaded with a pre-signed URL
maxExecutionsPerSecond	Maximum number of executions per second allowed
maxConcurrentDispatches	Maximum number of concurrent executions allowed
maxItemExecutionRuns	Maximum number of executions (including auto-retries) allowed per batch item before declaring the item as failed

The workflowInput JSON must have the structure described below:

Field	Description	Type
items	A list of dictionaries with input data for the execution of each batch item. This field is designed for quick tests of up to 10 items	Array
rawPackageIds	A list of previously created package IDs containing attachments with information of the batch items that will be read, validated, and processed during batch execution. Up to 5 packages can be sent	Array
customInput	Custom formatted input	Object

Headers

Header	Description
x-tags	Tags for the execution, comma-separated

Request Example

{
  "label": "Batch Loan Approval",
  "description": "Workflow for batch loan approval",
  "workflowInput": {
    "items": [
      { "person_id": "9999999999" },
      { "person_id": "1234567890" }
    ],
    "customInput": {},
    "rawPackageIds": []
  },
  "attachmentFileNames": [
    "file-name-returned-with-pre-signed-url.xlsx",
    "another-file-name-returned-with-pre-signed-url.xlsx"
  ],
  "maxExecutionsPerSecond": 1,
  "maxConcurrentDispatches": 1,
  "maxItemExecutionRuns": 2
}

Successful Response

{
    "executionBatchId": "009bddb2-1856-4afc-ae61-c243b7eb7e83",
    "workflowId": "072386f4-42c1-4685-ad5f-35a724486b24",
    "workflowAlias": "kyc",
    "workflowVersion": "v0",
    "executedAt": "2024-12-12T17:54:02.677597"
}

Error Handling

The API can return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page