Upload Cohort

curl --request POST \
  --url https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/deployments/{deployment_id}/cohorts/upload \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form 'name=April Users 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}/deployments/{deployment_id}/cohorts/upload"

files = {
    "cohort_file": ("example-file", open("example-file", "rb")),
    "cohort_transformation_file": ("example-file", open("example-file", "rb"))
}
payload = { "name": "April Users 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 Users Batch 1');
form.append('cohort_file', '(binary CSV file)');
form.append('cohort_transformation_file', '(binary JSON file)');

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}/deployments/{deployment_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}/deployments/{deployment_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 Users 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(binary CSV file)\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(binary JSON file)\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}/deployments/{deployment_id}/cohorts/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Users 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(binary CSV file)\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(binary JSON file)\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}/deployments/{deployment_id}/cohorts/upload")
  .header("X-API-Key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Users 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(binary CSV file)\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(binary JSON file)\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/deployments/{deployment_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 Users 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(binary CSV file)\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(binary JSON file)\r\n-----011000010111000001101001--"

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

{
  "name": "April Users Batch 1",
  "cohort_id": "coh-x1y2z3",
  "status": "completed",
  "source_type": "file_upload",
  "result": {
    "total_records": 5000,
    "valid_records": 4850,
    "rejected_records": 150
  },
  "created_by": "user@company.com",
  "created_at": "2026-04-01T09:00:00Z",
  "updated_by": null,
  "updated_at": "2026-04-01T09:02:30Z"
}

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

POST

orgs

{org_id}

workspaces

{workspace_id}

deployments

{deployment_id}

cohorts

upload

Upload Cohort

curl --request POST \
  --url https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/deployments/{deployment_id}/cohorts/upload \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form 'name=April Users 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}/deployments/{deployment_id}/cohorts/upload"

files = {
    "cohort_file": ("example-file", open("example-file", "rb")),
    "cohort_transformation_file": ("example-file", open("example-file", "rb"))
}
payload = { "name": "April Users 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 Users Batch 1');
form.append('cohort_file', '(binary CSV file)');
form.append('cohort_transformation_file', '(binary JSON file)');

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}/deployments/{deployment_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}/deployments/{deployment_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 Users 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(binary CSV file)\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(binary JSON file)\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}/deployments/{deployment_id}/cohorts/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Users 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(binary CSV file)\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(binary JSON file)\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}/deployments/{deployment_id}/cohorts/upload")
  .header("X-API-Key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nApril Users 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(binary CSV file)\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(binary JSON file)\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apps.sarvam.ai/api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/deployments/{deployment_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 Users 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(binary CSV file)\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(binary JSON file)\r\n-----011000010111000001101001--"

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

{
  "name": "April Users Batch 1",
  "cohort_id": "coh-x1y2z3",
  "status": "completed",
  "source_type": "file_upload",
  "result": {
    "total_records": 5000,
    "valid_records": 4850,
    "rejected_records": 150
  },
  "created_by": "user@company.com",
  "created_at": "2026-04-01T09:00:00Z",
  "updated_by": null,
  "updated_at": "2026-04-01T09:02:30Z"
}

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

Overview

A cohort gives your deployment user context. When a known user calls in, the agent receives their personalized variables (name, balance, language preference, etc.) — making the conversation feel tailored rather than generic.

How phone number matching works

The phone number is the lookup key. When an inbound call arrives, the system:

Extracts the caller’s phone number
Looks it up across all cohorts uploaded to this deployment
If found → loads that user’s agent variables into the conversation
If not found → the agent handles the call without any personalized context

This means your CSV must include a phone number column — it’s how the system connects “this caller” to “this row of data.”

Multiple cohorts with the same phone number

If you upload multiple cohorts and the same phone number appears in more than one, the most recently uploaded cohort takes precedence. The system always uses the latest context for a given phone number. This is useful when you need to refresh user data — simply upload a new cohort with updated values. You don’t need to delete the old one.

Scenario	What happens
Phone number in one cohort	That cohort’s variables are used
Phone number in multiple cohorts	The latest cohort’s variables are used
Phone number not in any cohort	Agent handles the call without personalized context

Transformation config

The transformation config tells the system how to read your CSV:

{
  "phone_number": { "column_name": "mobile", "country_code": "IN" },
  "app_variables": {
    "customer_name": { "column_name": "name" },
    "outstanding_amount": { "column_name": "balance" },
    "due_date": { "column_name": "payment_due" }
  },
  "app_overrides": {
    "initial_language_name": { "column_name": "preferred_language" }
  }
}

Section	Purpose
`phone_number`	Required. Which column contains the user’s phone number. This is the key used to match inbound callers.
`app_variables`	Maps CSV columns → agent variables. Keys must match the agent’s declared variables.
`app_overrides`	Override agent-level settings per user (language, initial message, initial state)

Phone number normalization

The system normalizes all phone numbers to E.164 format using the country_code you provide. For example, with "country_code": "IN":

9876543210 → +919876543210
09876543210 → +919876543210
+919876543210 → +919876543210 (already valid)

This ensures matching works correctly regardless of how the number is formatted in your CSV.

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
app_variables keys must match the agent’s declared variables

Row-level — individual rows are rejected, the rest continue:

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

Statuses

Status	Meaning
`processing`	Upload queued and being validated
`completed`	Processing finished — user context is live
`failed`	Processing failed (upload-level error)

Checking for rejected records

After status becomes completed, check result.rejected_records:

GET /deployments/{id}/cohorts/{cohort_id}

If result.rejected_records > 0, download the rejection file to see which rows failed and why:

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

Fix the data issues in your CSV and re-upload. Rejected users won’t have personalized context available when they call.

Authorizations

X-API-Key

string

header

required

Path Parameters

org_id

string

required

workspace_id

string

required

deployment_id

string

required

Body

multipart/form-data

Multipart form data for uploading a cohort.

name

string

required

Cohort name (1-50 characters)

Maximum string length: 50

Pattern: ^[\w\- ]{1,50}$

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 cohort

cohort_id

string

required

Unique identifier for the cohort

Example:

"coh-x1y2z3"

status

enum<string>

required

Current processing status

Available options:

processing,

completed,

failed

source_type

enum<string>

required

How the cohort was uploaded

Available options:

pre_signed_url,

file_upload

created_by

string

required

User who created this cohort

Example:

"user@company.com"

created_at

string<date-time>

required

Timestamp when created (ISO 8601)

Example:

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

updated_at

string<date-time>

required

Timestamp when last updated (ISO 8601)

Example:

"2026-04-01T09:02:30Z"

result

CohortResult · object | null

Processing result with record counts

Show child attributes

updated_by

string | null

User who last updated this cohort

Delete Deployment List Cohorts

Deployments

Campaigns

Instant Outbound

Analytics

BYOK (Bring Your Own Key) API

Upload Cohort

Overview

How phone number matching works

Multiple cohorts with the same phone number

Transformation config

Phone number normalization

Validation

Statuses

Checking for rejected records

Authorizations

Path Parameters

Body

Response

​Overview

​How phone number matching works

​Multiple cohorts with the same phone number

​Transformation config

​Phone number normalization

​Validation

​Statuses

​Checking for rejected records

Authorizations

Path Parameters

Body

Response

Overview

How phone number matching works

Multiple cohorts with the same phone number

Transformation config

Phone number normalization

Validation

Statuses

Checking for rejected records