Upload Cohort

curl --request POST \
  --url https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form 'name=April Batch 1' \
  --form cohort_file='@example-file' \
  --form cohort_transformation_file='@example-file'

import requests

url = "https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload"

files = {
    "cohort_file": ("example-file", open("example-file", "rb")),
    "cohort_transformation_file": ("example-file", open("example-file", "rb"))
}
payload = { "name": "April Batch 1" }
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('name', 'April Batch 1');
form.append('cohort_file', '<string>');
form.append('cohort_transformation_file', '<string>');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload', 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://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Batch 1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_transformation_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "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://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Batch 1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_transformation_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

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

	req.Header.Add("X-API-Key", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload")
  .header("X-API-Key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Batch 1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_transformation_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload")

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.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Batch 1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_transformation_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "name": "April Batch 1",
  "cohort_id": "coh-x1y2z3",
  "status": "completed",
  "source_type": "file_upload",
  "result": {
    "total_records": 10000,
    "valid_records": 9750,
    "rejected_records": 250
  },
  "created_by": "user@company.com",
  "created_at": "2026-04-01T09:00:00Z",
  "updated_by": null,
  "updated_at": "2026-04-01T09:05:00Z"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "data": {
      "details": {}
    }
  }
}

POST

orgs

{org_id}

workspaces

{workspace_id}

campaigns

{campaign_id}

cohorts

upload

Upload Cohort

curl --request POST \
  --url https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form 'name=April Batch 1' \
  --form cohort_file='@example-file' \
  --form cohort_transformation_file='@example-file'

import requests

url = "https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload"

files = {
    "cohort_file": ("example-file", open("example-file", "rb")),
    "cohort_transformation_file": ("example-file", open("example-file", "rb"))
}
payload = { "name": "April Batch 1" }
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('name', 'April Batch 1');
form.append('cohort_file', '<string>');
form.append('cohort_transformation_file', '<string>');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload', 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://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Batch 1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_transformation_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "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://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Batch 1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_transformation_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

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

	req.Header.Add("X-API-Key", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload")
  .header("X-API-Key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Batch 1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_transformation_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}/cohorts/upload")

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.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Batch 1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"cohort_transformation_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "name": "April Batch 1",
  "cohort_id": "coh-x1y2z3",
  "status": "completed",
  "source_type": "file_upload",
  "result": {
    "total_records": 10000,
    "valid_records": 9750,
    "rejected_records": 250
  },
  "created_by": "user@company.com",
  "created_at": "2026-04-01T09:00:00Z",
  "updated_by": null,
  "updated_at": "2026-04-01T09:05:00Z"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "data": {
      "details": {}
    }
  }
}

Overview

A cohort is a batch of users uploaded as a CSV along with a transformation config (JSON) that maps your CSV columns to phone numbers and agent variables. Uploading a cohort triggers background processing that validates each row and queues calls for valid records.

{
  "phone_number": { "column_name": "mobile" },
  "user_identifier": { "column_name": "customer_id", "required": true },
  "app_variables": {
    "customer_name": { "column_name": "name" },
    "loan_amount": { "column_name": "amount" }
  },
  "app_overrides": {
    "initial_language_name": { "column_name": "language" }
  }
}

Validation

Blocking — rejects the entire upload:

All referenced column_name values must exist as CSV headers
CSV must have at least one data row
app_overrides keys must be one of: initial_bot_message, initial_state_name, initial_language_name
For agent campaigns: app_variables keys must match the agent’s declared variables

Row-level — row is rejected, the rest continue:

Phone number must be valid (normalized to E.164)
Required columns must be non-empty
Formatting functions (if configured) must succeed

Rejected rows are collected into a downloadable CSV with an appended rejected_reason column.

Statuses

Status	Description
`processing`	Upload queued and being validated
`completed`	Processing finished; call queue populated
`failed`	Processing failed (upload-level error, not row-level)

Rejected records

Once status is completed, always check result.rejected_records. Poll:

GET /campaigns/{id}/cohorts/{cohort_id}

If result.rejected_records > 0, download the file to see which rows failed and why, then fix the data and re-upload:

GET /campaigns/{id}/cohorts/{cohort_id}/files?file_type=rejected_records

Rejected users will not be called. Catching and re-uploading them before the campaign goes live ensures maximum coverage.

Authorizations

X-API-Key

string

header

required

Path Parameters

org_id

string

required

workspace_id

string

required

campaign_id

string

required

Body

multipart/form-data

name

string

required

Name of the resource

Example:

"April Batch 1"

cohort_file

file

required

CSV file containing the cohort data

cohort_transformation_file

file

required

JSON file defining how CSV columns map to agent variables

Response

Successful Response

Cohort metadata including processing status and result counts.

name

string

required

Name of the resource

Example:

"April Batch 1"

cohort_id

string

required

Unique identifier for the cohort

Example:

"coh-x1y2z3"

status

enum<string>

required

Current status

Available options:

processing,

completed,

failed

Example:

"completed"

source_type

enum<string>

required

How the cohort was uploaded

Available options:

pre_signed_url,

file_upload

Example:

"file_upload"

created_by

string

required

User who created this resource

Example:

"user@company.com"

created_at

string<date-time>

required

Timestamp when the resource was created (ISO 8601)

Example:

"2026-04-01T09:00:00Z"

updated_at

string<date-time>

required

Timestamp when the resource was last updated (ISO 8601)

Example:

"2026-04-01T09:05:00Z"

result

CohortResult · object | null

Processing result with record counts

Show child attributes

Example:

{
  "total_records": 1000,
  "valid_records": 980,
  "rejected_records": 20
}

updated_by

string | null

User who last updated this resource

Example:

"user@example.com"

Webhook Payload List Cohorts

Deployments

Campaigns

Instant Outbound

Analytics

BYOK (Bring Your Own Key) API

Upload Cohort

Overview

Validation

Statuses

Rejected records

Authorizations

Path Parameters

Body

Response

​Overview

​Validation

​Statuses

​Rejected records

Authorizations

Path Parameters

Body

Response

Overview

Validation

Statuses

Rejected records