Workflow APIs

Workflow APIs enable you to build custom company and people search workflows with AI-powered criteria extraction, multi-step processing, and real-time streaming.

Workflow Types

ChordianAI supports two types of workflows:

Company Workflows - Search and enrich company data
People Workflows - Search and enrich people/contact data

Both follow the same lifecycle: Start → Continue → Monitor → Complete

Company Workflow Endpoints

Start Company Workflow

Start a new company search workflow with a natural language prompt.

POST /api/workflow/start

Request Body

{
  "prompt": "Find SaaS companies in San Francisco with 50-200 employees",
  "serviceId": "your-service-id",
  "total_target": 25,
  "type": "list_builder",
  "threadId": "optional-existing-thread-id",
  "list_name": "My Custom List",
  "list_description": "List of SaaS companies",
  "list_id": "optional-list-id-to-update",
  "additional_criteria": [
    {
      "name": "Revenue",
      "value": "$1M-$10M",
      "column_name": "revenue",
      "columnType": "text",
      "description": "Annual recurring revenue",
      "type": "hard_filter"
    }
  ]
}

Field	Type	Required	Description
`prompt`	string	✅	Natural language search query
`serviceId`	string	✅	Service ID for credit tracking
`total_target`	integer	❌	Target number of results (default: 25)
`type`	string	❌	Workflow type: `list_builder`, `base_data_list`, or `predefined_agent`
`threadId`	string	❌	Existing thread ID to continue
`list_name`	string	❌	Custom name for the list
`list_description`	string	❌	Description for the list
`list_id`	string	❌	Existing list ID to update
`additional_criteria`	array	❌	Pre-defined criteria items (see schema below)

Criteria Item Schema

Each item in additional_criteria should have the following structure:

Field	Type	Description
`name`	string	Display name of the criteria
`value`	string	Value to search for
`column_name`	string	Database column name (snake_case)
`columnType`	string	UI column type (e.g., ‘text’, ‘badge’)
`description`	string	Description for the criteria
`type`	string	Criteria type

Response

Returns a streaming response with real-time updates:

{
  "thread_id": "abc123-def456",
  "status": "processing",
  "current_step": "criteria_extraction",
  "criteria": [
    {
      "name": "Industry",
      "value": "SaaS",
      "column_name": "industry",
      "description": "Software as a Service companies"
    },
    {
      "name": "Location",
      "value": "San Francisco",
      "column_name": "location"
    }
  ]
}

Example

curl -X POST https://chordian-core.chordian.ai/api/workflow/start \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find AI startups in New York with Series A funding",
    "serviceId": "srv_123",
    "total_target": 50
  }'

SDK Examples

import requests
 
BASE_URL = "https://chordian-core.chordian.ai"
 
response = requests.post(
    f"{BASE_URL}/api/workflow/start",
    json={
        "prompt": "Find AI startups in New York with Series A funding",
        "serviceId": "srv_123",
        "total_target": 50
    }
)
 
data = response.json()
thread_id = data["thread_id"]
print(f"Workflow started: {thread_id}")

const axios = require('axios');
 
const BASE_URL = 'https://chordian-core.chordian.ai';
 
async function startWorkflow() {
  const response = await axios.post(
    `${BASE_URL}/api/workflow/start`,
    {
      prompt: 'Find AI startups in New York with Series A funding',
      serviceId: 'srv_123',
      total_target: 50
    }
  );
 
  const { thread_id } = response.data;
  console.log(`Workflow started: ${thread_id}`);
  return thread_id;
}

import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
 
public class WorkflowExample {
    private static final String BASE_URL = "https://chordian-core.chordian.ai";
 
    public static String startWorkflow() throws Exception {
        CloseableHttpClient client = HttpClients.createDefault();
        HttpPost request = new HttpPost(BASE_URL + "/api/workflow/start");
        
        String json = "{\"prompt\":\"Find AI startups in New York with Series A funding\"," +
                     "\"serviceId\":\"srv_123\"," +
                     "\"total_target\":50}";
        
        request.setEntity(new StringEntity(json));
        request.setHeader("Content-Type", "application/json");
        
        var response = client.execute(request);
        String responseBody = EntityUtils.toString(response.getEntity());
        
        JsonObject jsonResponse = JsonParser.parseString(responseBody).getAsJsonObject();
        String threadId = jsonResponse.get("thread_id").getAsString();
        
        System.out.println("Workflow started: " + threadId);
        return threadId;
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
 
public class WorkflowExample
{
    private static readonly string BaseUrl = "https://chordian-core.chordian.ai";
 
    public static async Task<string> StartWorkflow()
    {
        using var client = new HttpClient();
        
        var payload = new
        {
            prompt = "Find AI startups in New York with Series A funding",
            serviceId = "srv_123",
            total_target = 50
        };
        
        var content = new StringContent(
            JsonConvert.SerializeObject(payload),
            Encoding.UTF8,
            "application/json"
        );
        
        var response = await client.PostAsync(
            $"{BaseUrl}/api/workflow/start",
            content
        );
        
        var result = await response.Content.ReadAsStringAsync();
        var json = JObject.Parse(result);
        var threadId = json["thread_id"].ToString();
        
        Console.WriteLine($"Workflow started: {threadId}");
        return threadId;
    }
}

Continue Company Workflow

Continue a workflow with additional criteria or modifications.

POST /api/workflow/continue

Request Body

{
  "thread_id": "abc123-def456",
  "total_target": 50,
  "serviceId": "your-service-id",
  "additional_criteria": [
    {
      "name": "Revenue",
      "value": "$1M-$10M",
      "column_name": "revenue",
      "columnType": "text",
      "description": "Annual revenue range",
      "type": "hard_filter"
    }
  ],
  "current_criteria": [
    {
      "name": "Industry",
      "value": "SaaS",
      "column_name": "industry",
      "columnType": "text",
      "description": "Software as a Service companies",
      "type": "hard_filter"
    }
  ]
}

Field	Type	Required	Description
`thread_id`	string	✅	Thread ID from start workflow
`total_target`	integer	✅	Total target count for results
`serviceId`	string	❌	Service ID for credit checking
`additional_criteria`	array	❌	New criteria to add (see schema below)
`current_criteria`	array	❌	Existing criteria (see schema below)

Criteria Item Schema

Each item in additional_criteria and current_criteria should have the following structure:

Field	Type	Description
`name`	string	Display name of the criteria
`value`	string	Value to search for
`column_name`	string	Database column name (snake_case)
`columnType`	string	UI column type (e.g., ‘text’, ‘badge’)
`description`	string	Description for the criteria
`type`	string	Criteria type

Get Workflow Status

Get the current status and results of a workflow.

GET /api/workflow/status/{thread_id}

Response

{
  "thread_id": "abc123-def456",
  "current_step": "enrichment",
  "category": "Technology",
  "criteria": [],
  "error_message": null,
  "total_target": 50,
  "table_structure": {
    "columns": [
      {
        "id": "company_name",
        "header": "Company Name",
        "type": "fixed",
        "width": 180,
        "required": true,
        "columnType": "text",
        "dataType": "string"
      }
    ],
    "rows": [
      {
        "id": "row_1",
        "cells": {
          "company_name": {
            "row_id": "row_1",
            "column_id": "company_name",
            "value": "Acme Corp",
            "status": "completed",
            "metadata": {},
            "expandable": false
          }
        },
        "step_source": "human_input",
        "metadata": {}
      }
    ],
    "total_target": 50,
    "current_count": 1
  },
  "all_companies": [
    {
      "name": "Acme Corp",
      "website": "acme.com"
    }
  ],
  "step_companies": {
    "enrichment": [
      {
        "name": "Acme Corp",
        "employees": 100
      }
    ]
  },
  "title": "SaaS Companies",
  "description": "List of SaaS companies in SF",
  "goal": {},
  "processed_companies": [
    "acme.com"
  ]
}

List All Workflow Threads

Get a list of all workflow threads.

GET /api/workflow/threads

Response

[
  {
    "thread_id": "abc123",
    "tenant_id": "tenant_001",
    "order_id": "order_001",
    "status": "completed",
    "created_at": "2025-02-07T08:00:00Z",
    "last_updated": "2025-02-07T08:15:00Z"
  }
]

Restore Workflow State

Restore a workflow state from database using list ID.

GET /api/workflow/restore/{list_id}

Response

{
  "list_id": "list_abc123",
  "status": "restored",
  "criteria": [],
  "total_target": 25,
  "table_structure": {
    "columns": [
      {
        "id": "company_name",
        "header": "Company Name",
        "type": "fixed",
        "width": 180,
        "required": false,
        "columnType": "text",
        "dataType": "string"
      }
    ],
    "rows": [
      {
        "id": "row_1",
        "cells": {
          "company_name": {
            "row_id": "row_1",
            "column_id": "company_name",
            "value": "Acme Corp",
            "status": "pending",
            "metadata": {},
            "expandable": false
          }
        },
        "step_source": "human_input",
        "metadata": {}
      }
    ],
    "total_target": 25,
    "current_count": 0
  },
  "title": "My Saved List",
  "description": "List description",
  "thread_id": "abc123",
  "listType": "company_search",
  "supervisor_started": false
}

Error Response (422 Validation Error)

{
  "detail": [
    {
      "loc": [
        "path",
        "list_id"
      ],
      "msg": "Invalid list ID format",
      "type": "value_error"
    }
  ]
}

Stop Workflow

Stop a running workflow.

POST /api/workflow/stop/{thread_id}

Successful Response (200 OK)

Returns the thread ID of the stopped workflow.

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "path",
        "thread_id"
      ],
      "msg": "Invalid thread ID format",
      "type": "value_error"
    }
  ]
}

Remove Criteria

Remove a criteria from workflow and update table structure.

POST /api/workflow/remove-criteria

Request Body

{
  "additionalProp1": {}
}

Successful Response (200 OK)

Returns the updated table structure or confirmation message.

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

People Workflow Endpoints

People workflows follow the same pattern as company workflows but search for individuals/contacts.

Start People Workflow

POST /api/workflow/people/start

Request Body

{
  "prompt": "Find software engineers in Seattle",
  "threadId": "optional-thread-id",
  "total_target": 25,
  "additional_criteria": [
    {
      "name": "Location",
      "value": "Seattle, WA",
      "column_name": "location",
      "columnType": "text",
      "description": "City and State",
      "type": "hard_filter"
    }
  ],
  "type": "people_search",
  "list_name": "Seattle Engineers",
  "list_description": "List of software engineers in Seattle",
  "serviceId": "your-service-id",
  "list_id": "optional-list-id"
}

Successful Response (200 OK)

Returns thread ID string.

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "body",
        "prompt"
      ],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Continue People Workflow

POST /api/workflow/people/continue

Request Body

{
  "thread_id": "string",
  "additional_criteria": [
    {
      "name": "string",
      "value": "string",
      "column_name": "string",
      "columnType": "string",
      "description": "string",
      "type": "string"
    }
  ],
  "current_criteria": [
    {
      "name": "string",
      "value": "string",
      "column_name": "string",
      "columnType": "string",
      "description": "string",
      "type": "string"
    }
  ],
  "total_target": 0,
  "serviceId": "string"
}

Successful Response (200 OK)

Returns thread ID string.

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get People Workflow Status

GET /api/workflow/people/status/{thread_id}

Successful Response (200 OK)

{
  "thread_id": "string",
  "current_step": "string",
  "category": "string",
  "criteria": [],
  "error_message": "string",
  "total_target": 0,
  "table_structure": {
    "columns": [
      {
        "id": "string",
        "header": "string",
        "type": "string",
        "width": 180,
        "required": false,
        "columnType": "string",
        "dataType": "string"
      }
    ],
    "rows": [
      {
        "id": "string",
        "cells": {
          "additionalProp1": {
            "row_id": "string",
            "column_id": "string",
            "value": "string",
            "status": "pending",
            "metadata": {
              "additionalProp1": {}
            },
            "expandable": false
          },
          "additionalProp2": {
            "row_id": "string",
            "column_id": "string",
            "value": "string",
            "status": "pending",
            "metadata": {
              "additionalProp1": {}
            },
            "expandable": false
          },
          "additionalProp3": {
            "row_id": "string",
            "column_id": "string",
            "value": "string",
            "status": "pending",
            "metadata": {
              "additionalProp1": {}
            },
            "expandable": false
          }
        },
        "step_source": "string",
        "metadata": {
          "additionalProp1": {}
        }
      }
    ],
    "total_target": 25,
    "current_count": 0
  },
  "all_companies": [
    {
      "additionalProp1": {}
    }
  ],
  "step_companies": {
    "additionalProp1": [
      {
        "additionalProp1": {}
      }
    ],
    "additionalProp2": [
      {
        "additionalProp1": {}
      }
    ],
    "additionalProp3": [
      {
        "additionalProp1": {}
      }
    ]
  },
  "title": "string",
  "description": "string",
  "goal": {
    "additionalProp1": {}
  },
  "processed_companies": [
    "string"
  ]
}

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

List People Workflow Threads

GET /api/workflow/people/threads

Successful Response (200 OK)

[
  {
    "thread_id": "string",
    "tenant_id": "string",
    "order_id": "string",
    "status": "string",
    "created_at": "2026-02-08T10:40:43.965Z",
    "last_updated": "2026-02-08T10:40:43.965Z"
  }
]

Stop People Workflow

POST /api/workflow/people/stop/{thread_id}

Successful Response (200 OK)

Returns the thread ID of the stopped workflow.

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Remove People Criteria

POST /api/workflow/people/remove-criteria

Request Body

{
  "additionalProp1": {}
}

Successful Response (200 OK)

Returns the updated table structure or confirmation message.

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Workflow Lifecycle

Best Practices

? Info: Tip: Start with a clear, specific prompt for better criteria extraction.

Clear Prompts - Use specific, detailed prompts for accurate criteria extraction
Monitor Progress - Poll the status endpoint to track workflow progress
Handle Streaming - Implement SSE listeners for real-time updates
Error Handling - Always check response status and handle errors gracefully
Resource Cleanup - Stop workflows when no longer needed

Next Steps

Learn about Company Search APIs and People Search APIs for enrichment workflows
View Request Schemas
Follow the Workflow Tutorial

MCP Server Getting Started