Assign to Workflow

curl --request POST \
  --url https://api.callkaro.ai/workflow/assign \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "to_number": "+919876543210",
  "workflow_id": "6ab6243266ba77dbaf2276c7",
  "attributes": [
    {
      "key": "first_name",
      "value": "Rahul",
      "replace": true
    },
    {
      "key": "city",
      "value": "Pune",
      "replace": false
    }
  ],
  "schedule_at": "2026-12-31T09:30:00"
}
'

import requests

url = "https://api.callkaro.ai/workflow/assign"

payload = {
    "to_number": "+919876543210",
    "workflow_id": "6ab6243266ba77dbaf2276c7",
    "attributes": [
        {
            "key": "first_name",
            "value": "Rahul",
            "replace": True
        },
        {
            "key": "city",
            "value": "Pune",
            "replace": False
        }
    ],
    "schedule_at": "2026-12-31T09:30:00"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to_number: '+919876543210',
    workflow_id: '6ab6243266ba77dbaf2276c7',
    attributes: [
      {key: 'first_name', value: 'Rahul', replace: true},
      {key: 'city', value: 'Pune', replace: false}
    ],
    schedule_at: '2026-12-31T09:30:00'
  })
};

fetch('https://api.callkaro.ai/workflow/assign', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.callkaro.ai/workflow/assign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'to_number' => '+919876543210',
    'workflow_id' => '6ab6243266ba77dbaf2276c7',
    'attributes' => [
        [
                'key' => 'first_name',
                'value' => 'Rahul',
                'replace' => true
        ],
        [
                'key' => 'city',
                'value' => 'Pune',
                'replace' => false
        ]
    ],
    'schedule_at' => '2026-12-31T09:30:00'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.callkaro.ai/workflow/assign"

	payload := strings.NewReader("{\n  \"to_number\": \"+919876543210\",\n  \"workflow_id\": \"6ab6243266ba77dbaf2276c7\",\n  \"attributes\": [\n    {\n      \"key\": \"first_name\",\n      \"value\": \"Rahul\",\n      \"replace\": true\n    },\n    {\n      \"key\": \"city\",\n      \"value\": \"Pune\",\n      \"replace\": false\n    }\n  ],\n  \"schedule_at\": \"2026-12-31T09:30:00\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.callkaro.ai/workflow/assign")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to_number\": \"+919876543210\",\n  \"workflow_id\": \"6ab6243266ba77dbaf2276c7\",\n  \"attributes\": [\n    {\n      \"key\": \"first_name\",\n      \"value\": \"Rahul\",\n      \"replace\": true\n    },\n    {\n      \"key\": \"city\",\n      \"value\": \"Pune\",\n      \"replace\": false\n    }\n  ],\n  \"schedule_at\": \"2026-12-31T09:30:00\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.callkaro.ai/workflow/assign")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"to_number\": \"+919876543210\",\n  \"workflow_id\": \"6ab6243266ba77dbaf2276c7\",\n  \"attributes\": [\n    {\n      \"key\": \"first_name\",\n      \"value\": \"Rahul\",\n      \"replace\": true\n    },\n    {\n      \"key\": \"city\",\n      \"value\": \"Pune\",\n      \"replace\": false\n    }\n  ],\n  \"schedule_at\": \"2026-12-31T09:30:00\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "done",
  "message": "Workflow started",
  "run_id": "wf_run_8c1f2a",
  "enrollment_id": "3f6c2b1e-7a4d-4c8e-9b1a-2d5e8f0c4a7b",
  "attributes": {
    "updated": [
      "first_name"
    ],
    "kept_existing": [
      "city"
    ],
    "ignored": [],
    "invalid": []
  }
}

{
  "status": "error",
  "message": "schedule_at must be YYYY-MM-DDTHH:mm:ss (IST)"
}

{
  "status": "error",
  "message": "Missing API key"
}

{
  "status": "error",
  "message": "Workflow not found"
}

{
  "status": "error",
  "message": "This number is already running in this workflow"
}

{
  "status": "error",
  "message": "Missing required field: to_number"
}

POST

workflow

assign

Assign to Workflow

curl --request POST \
  --url https://api.callkaro.ai/workflow/assign \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "to_number": "+919876543210",
  "workflow_id": "6ab6243266ba77dbaf2276c7",
  "attributes": [
    {
      "key": "first_name",
      "value": "Rahul",
      "replace": true
    },
    {
      "key": "city",
      "value": "Pune",
      "replace": false
    }
  ],
  "schedule_at": "2026-12-31T09:30:00"
}
'

import requests

url = "https://api.callkaro.ai/workflow/assign"

payload = {
    "to_number": "+919876543210",
    "workflow_id": "6ab6243266ba77dbaf2276c7",
    "attributes": [
        {
            "key": "first_name",
            "value": "Rahul",
            "replace": True
        },
        {
            "key": "city",
            "value": "Pune",
            "replace": False
        }
    ],
    "schedule_at": "2026-12-31T09:30:00"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to_number: '+919876543210',
    workflow_id: '6ab6243266ba77dbaf2276c7',
    attributes: [
      {key: 'first_name', value: 'Rahul', replace: true},
      {key: 'city', value: 'Pune', replace: false}
    ],
    schedule_at: '2026-12-31T09:30:00'
  })
};

fetch('https://api.callkaro.ai/workflow/assign', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.callkaro.ai/workflow/assign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'to_number' => '+919876543210',
    'workflow_id' => '6ab6243266ba77dbaf2276c7',
    'attributes' => [
        [
                'key' => 'first_name',
                'value' => 'Rahul',
                'replace' => true
        ],
        [
                'key' => 'city',
                'value' => 'Pune',
                'replace' => false
        ]
    ],
    'schedule_at' => '2026-12-31T09:30:00'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.callkaro.ai/workflow/assign"

	payload := strings.NewReader("{\n  \"to_number\": \"+919876543210\",\n  \"workflow_id\": \"6ab6243266ba77dbaf2276c7\",\n  \"attributes\": [\n    {\n      \"key\": \"first_name\",\n      \"value\": \"Rahul\",\n      \"replace\": true\n    },\n    {\n      \"key\": \"city\",\n      \"value\": \"Pune\",\n      \"replace\": false\n    }\n  ],\n  \"schedule_at\": \"2026-12-31T09:30:00\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.callkaro.ai/workflow/assign")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to_number\": \"+919876543210\",\n  \"workflow_id\": \"6ab6243266ba77dbaf2276c7\",\n  \"attributes\": [\n    {\n      \"key\": \"first_name\",\n      \"value\": \"Rahul\",\n      \"replace\": true\n    },\n    {\n      \"key\": \"city\",\n      \"value\": \"Pune\",\n      \"replace\": false\n    }\n  ],\n  \"schedule_at\": \"2026-12-31T09:30:00\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.callkaro.ai/workflow/assign")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"to_number\": \"+919876543210\",\n  \"workflow_id\": \"6ab6243266ba77dbaf2276c7\",\n  \"attributes\": [\n    {\n      \"key\": \"first_name\",\n      \"value\": \"Rahul\",\n      \"replace\": true\n    },\n    {\n      \"key\": \"city\",\n      \"value\": \"Pune\",\n      \"replace\": false\n    }\n  ],\n  \"schedule_at\": \"2026-12-31T09:30:00\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "done",
  "message": "Workflow started",
  "run_id": "wf_run_8c1f2a",
  "enrollment_id": "3f6c2b1e-7a4d-4c8e-9b1a-2d5e8f0c4a7b",
  "attributes": {
    "updated": [
      "first_name"
    ],
    "kept_existing": [
      "city"
    ],
    "ignored": [],
    "invalid": []
  }
}

{
  "status": "error",
  "message": "schedule_at must be YYYY-MM-DDTHH:mm:ss (IST)"
}

{
  "status": "error",
  "message": "Missing API key"
}

{
  "status": "error",
  "message": "Workflow not found"
}

{
  "status": "error",
  "message": "This number is already running in this workflow"
}

{
  "status": "error",
  "message": "Missing required field: to_number"
}

Puts one phone number into a workflow from your own system, such as a CRM, a website form or your backend. It does the same as assigning a contact from the CRM, and can save details on the contact first so every step of the workflow can use them.

Quick Example

curl -X POST "https://api.callkaro.ai/workflow/assign" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "to_number": "+919876543210",
    "workflow_id": "6ab6243266ba77dbaf2276c7",
    "attributes": [
      { "key": "first_name", "value": "Rahul", "replace": true }
    ]
  }'

Use Cases

New leads: start a follow-up workflow the moment a form is submitted or a lead is created in your CRM
Lifecycle events: put a customer into a renewal, payment-reminder or onboarding workflow when it happens in your system
Scheduled outreach: pass schedule_at to start the workflow at a set time, such as the morning after a sign-up

Where to find the values

Field	Where it comes from
`X-API-KEY`	API Key in the dashboard sidebar. Use the key of the account that owns the workflow.
`workflow_id`	Open the workflow in the dashboard. The ID is the last part of the URL.
`attributes[].key`	The name of an attribute in CRM → Attributes. See Attributes.

What happens on your account

The workflow is checked

The workflow must belong to the account the API key is for, and must have at least one step. A key from another account gets 404, the same answer as a workflow that does not exist.

The contact is saved

The number becomes a contact in your CRM if it is not one already, and the attributes you sent are saved on it.

The run starts

The number enters the workflow at Start, now or at schedule_at. Every step can read the saved attributes: as Contact values in conditions, in {{variables}}, and in a Send Call step’s call metadata.

The run then appears with the workflow’s other runs, as described in Enroll and Monitor.

How attributes are saved

Each row in attributes is a key, a value and an optional replace.

Matching names: key is matched to your CRM attributes ignoring case, spaces, underscores and hyphens, so "First Name" matches first_name.
replace: true overwrites a value the contact already has.
replace: false (the default) only fills an attribute that is empty. An existing value is kept.
Types: the value is checked against the attribute’s type. A number attribute needs a number, a date needs a date, and an enum value must be one of its options.
Edits made by hand win: a value someone typed into the CRM is never overwritten through the API, even with replace: true.

Only attributes that already exist in CRM → Attributes are saved. A key with no matching attribute is not created; it is listed under ignored in the response. Create the attribute first.

The response reports what happened to every row, so a typo does not go unnoticed:

"attributes": {
  "updated": ["first_name"],
  "kept_existing": ["city"],
  "ignored": ["frist_name"],
  "invalid": [{ "key": "age", "reason": "not a valid number" }]
}

Scheduling

schedule_at is a date and time in IST, written as YYYY-MM-DDTHH:mm:ss with two digits for the month and day: 2026-12-31T09:30:00, not 2026-12-31T9:30 or 2026-12-3T09:30:00. Leave it out to start now. A time that has already passed also starts now.

Errors worth handling

404 Workflow not found

The workflow ID is wrong, or the API key belongs to a different account from the workflow. Check both.

409 This number is already running in this workflow

The number is partway through this workflow already, so it is not started a second time. The attributes you sent are still saved. The number can be assigned again once its current run has finished.

400 This workflow has no steps yet / is no longer available

Add steps to the workflow and save it, or use a different workflow. Older AI workflows cannot take contacts through this endpoint.

400 schedule_at must be YYYY-MM-DDTHH:mm:ss (IST)

The date is not in the expected shape. Use two digits for every part and a T between the date and the time.

Do not retry a 400, 404 or 409: the same request will get the same answer. Only 5xx responses are worth retrying, and a retry can start the run if the first attempt had not.

Authorizations

X-API-KEY

string

header

required

API key from https://callkaro.ai/dashboard/api-key

Body

application/json

to_number

string

required

Phone number with country code. A leading + is optional.

Example:

"+919876543210"

workflow_id

string

required

ID of a normal workflow, from the end of its URL when you open it in the dashboard.

Example:

"6ab6243266ba77dbaf2276c7"

attributes

object[]

Values to save on the contact before the run starts.

Maximum array length: 50

Show child attributes

schedule_at

string

When the run should start, as YYYY-MM-DDTHH:mm:ss in IST (Asia/Kolkata). Omit it, or pass a time that has passed, to start now.

Example:

"2026-12-31T09:30:00"

Response

Run started or scheduled

status

string

Example:

"done"

message

string

Example:

"Workflow started"

run_id

string

ID of the run that was started

enrollment_id

string

ID shared by every run started in this request

attributes

object

What happened to each attribute you sent. Also returned on 409 and 500 responses, since the contact is saved before the run starts.

Show child attributes

​Quick Example

​Use Cases

​Where to find the values

​What happens on your account

​How attributes are saved

​Scheduling

​Errors worth handling

Authorizations

Body

Response

Quick Example

Use Cases

Where to find the values

What happens on your account

How attributes are saved

Scheduling

Errors worth handling