Add people to a batch
curl --request POST \
--url https://api.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"recipients": [
{
"person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76",
"variable_values": {
"personalization_line": "Your Monzo meetup talk was great.",
"ai:opening_line": "Your work on the card payments platform stood out."
}
}
]
}
'import requests
url = "https://api.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients"
payload = { "recipients": [
{
"person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76",
"variable_values": {
"personalization_line": "Your Monzo meetup talk was great.",
"ai:opening_line": "Your work on the card payments platform stood out."
}
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
recipients: [
{
person_id: '8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76',
variable_values: {
personalization_line: 'Your Monzo meetup talk was great.',
'ai:opening_line': 'Your work on the card payments platform stood out.'
}
}
]
})
};
fetch('https://api.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients', 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.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients",
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([
'recipients' => [
[
'person_id' => '8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76',
'variable_values' => [
'personalization_line' => 'Your Monzo meetup talk was great.',
'ai:opening_line' => 'Your work on the card payments platform stood out.'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients"
payload := strings.NewReader("{\n \"recipients\": [\n {\n \"person_id\": \"8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76\",\n \"variable_values\": {\n \"personalization_line\": \"Your Monzo meetup talk was great.\",\n \"ai:opening_line\": \"Your work on the card payments platform stood out.\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"recipients\": [\n {\n \"person_id\": \"8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76\",\n \"variable_values\": {\n \"personalization_line\": \"Your Monzo meetup talk was great.\",\n \"ai:opening_line\": \"Your work on the card payments platform stood out.\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"recipients\": [\n {\n \"person_id\": \"8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76\",\n \"variable_values\": {\n \"personalization_line\": \"Your Monzo meetup talk was great.\",\n \"ai:opening_line\": \"Your work on the card payments platform stood out.\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34",
"status": "ready",
"version": 3,
"source": "api",
"campaign": {
"id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84",
"name": "Senior Backend Engineer, Monzo"
},
"sender": {
"team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20",
"name": "Riya Kapoor",
"from_email": "riya@acmetalent.com"
},
"job": {
"id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13",
"title": "Senior Backend Engineer",
"pipeline_stage_id": "e4a0c3b7-1f5d-4a8e-9b2c-6d3f7a1e5c88",
"pipeline_stage": "Contacted"
},
"start": {
"mode": "scheduled",
"at": "2026-10-19T08:00:00.000Z",
"timezone": "Europe/London"
},
"created_by": {
"type": "api_key",
"id": "0d4b8f2e-6a1c-4e9b-b3d7-5f2a8c1e4b96",
"name": "Greenhouse sync"
},
"created_at": "2026-10-13T11:20:00.000Z",
"expires_at": "2026-10-14T11:24:10.000Z",
"started_at": null,
"progress": null,
"summary": {
"total": 5,
"preparing": 0,
"ready": 2,
"needs_input": 2,
"blocked": 1,
"excluded": 0,
"enrolled": 0,
"rejected_at_start": 0
},
"warnings": [
{
"code": "adds_to_job_pipeline",
"message": "2 people will be added to Senior Backend Engineer at Contacted.",
"details": {
"count": 2
}
},
{
"code": "contains_overrides",
"message": "Ana Ruiz is enrolled despite a do-not-contact or duplicate block.",
"details": {
"count": 1,
"names": [
"Ana Ruiz"
]
}
},
{
"code": "job_automation_will_run",
"message": "Moving people to this stage starts these automations: Notify hiring manager.",
"details": {
"automations": [
"Notify hiring manager"
]
}
}
],
"recipients": [
{
"recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21",
"person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40",
"name": "Sam Patel",
"email": "sam@gmail.com",
"status": "ready",
"issues": [
{
"code": "enrolled_in_other_campaign",
"message": "Also in 'Q4 platform engineers' (running).",
"details": {
"campaigns": [
"Q4 platform engineers"
]
}
}
],
"overrides": [],
"override_reason": null,
"enrollment_id": null,
"first_email_estimated_at": "2026-10-19T08:00:00.000Z"
},
{
"recipient_id": "b2d4f6a8-3c5e-4a7b-9d1f-2e4a6c8b0d32",
"person_id": "6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73",
"name": "Tom Reed",
"email": "tom@reed.dev",
"status": "needs_input",
"issues": [
{
"code": "missing_variables",
"message": "Fill in or leave blank: personalization_line.",
"details": {
"variables": [
"personalization_line"
]
}
}
],
"overrides": [],
"override_reason": null,
"enrollment_id": null,
"first_email_estimated_at": null
},
{
"recipient_id": "c3e5a7b9-4d6f-4b8c-ae2a-3f5b7d9c1e43",
"person_id": "9c4f1a7e-2d8b-4e6c-b3a9-5f1d7c3e8b24",
"name": "Priya Shah",
"email": "priya@shah.io",
"status": "blocked",
"issues": [
{
"code": "unsubscribed",
"message": "Unsubscribed from your emails on 2 Sep 2026."
}
],
"overrides": [],
"override_reason": null,
"enrollment_id": null,
"first_email_estimated_at": null
},
{
"recipient_id": "d4f6b8ca-5e7a-4c9d-bf3b-4a6c8e0d2f54",
"person_id": "4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95",
"name": "Mark Chen",
"email": "mark.chen@gmail.com",
"status": "needs_input",
"issues": [
{
"code": "company_do_not_contact",
"message": "Works at Globex, which is marked do not contact. Override with a reason to include them.",
"details": {
"companies": [
"Globex"
]
}
},
{
"code": "likely_bounce",
"message": "This email looks risky and may bounce."
}
],
"overrides": [],
"override_reason": null,
"enrollment_id": null,
"first_email_estimated_at": null
},
{
"recipient_id": "e5a7c9db-6f8b-4dae-8c4d-5b7d9f1e3a65",
"person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76",
"name": "Ana Ruiz",
"email": "ana.ruiz@gmail.com",
"status": "ready",
"issues": [
{
"code": "previously_in_campaign",
"message": "Was in this campaign before at ana.ruiz@gmail.com: enrolled 2 Sep 2026, then stopped.",
"details": {
"enrollment_id": "1c3e5a7b-8d9f-4a2c-b4e6-7f9a1c3e5b87",
"status": "stopped",
"enrolled_at": "2026-09-02T09:30:00.000Z"
}
}
],
"overrides": [
"company_do_not_contact"
],
"override_reason": "Their hiring manager asked us to reach out.",
"enrollment_id": null,
"first_email_estimated_at": "2026-10-19T08:00:00.000Z"
}
],
"sample": {
"recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21",
"subject": "Senior Backend Engineer role at Monzo",
"body_text": "Hi Sam,\n\nYour work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.\n\nYou can see the role here (https://jobs.stardex.com/acme-talent/senior-backend-engineer-k3f9a2). Open to a chat?\n\nRiya"
}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Campaigns
Add people to a batch
Adds people to a ready batch, checked the same way as at create. When the campaign uses AI variables and you don’t pass them, the batch is preparing again while they are written. Raises version. If another change to the batch lands first, it returns 409 BATCH_VERSION_CHANGED: read the batch and add them again. Only the API key or person who created the batch can change it. Needs campaigns:enroll.
POST
/
v1
/
campaigns
/
{id}
/
enrollment-batches
/
{batch_id}
/
recipients
Add people to a batch
curl --request POST \
--url https://api.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"recipients": [
{
"person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76",
"variable_values": {
"personalization_line": "Your Monzo meetup talk was great.",
"ai:opening_line": "Your work on the card payments platform stood out."
}
}
]
}
'import requests
url = "https://api.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients"
payload = { "recipients": [
{
"person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76",
"variable_values": {
"personalization_line": "Your Monzo meetup talk was great.",
"ai:opening_line": "Your work on the card payments platform stood out."
}
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
recipients: [
{
person_id: '8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76',
variable_values: {
personalization_line: 'Your Monzo meetup talk was great.',
'ai:opening_line': 'Your work on the card payments platform stood out.'
}
}
]
})
};
fetch('https://api.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients', 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.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients",
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([
'recipients' => [
[
'person_id' => '8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76',
'variable_values' => [
'personalization_line' => 'Your Monzo meetup talk was great.',
'ai:opening_line' => 'Your work on the card payments platform stood out.'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients"
payload := strings.NewReader("{\n \"recipients\": [\n {\n \"person_id\": \"8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76\",\n \"variable_values\": {\n \"personalization_line\": \"Your Monzo meetup talk was great.\",\n \"ai:opening_line\": \"Your work on the card payments platform stood out.\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"recipients\": [\n {\n \"person_id\": \"8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76\",\n \"variable_values\": {\n \"personalization_line\": \"Your Monzo meetup talk was great.\",\n \"ai:opening_line\": \"Your work on the card payments platform stood out.\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.stardex.ai/v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"recipients\": [\n {\n \"person_id\": \"8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76\",\n \"variable_values\": {\n \"personalization_line\": \"Your Monzo meetup talk was great.\",\n \"ai:opening_line\": \"Your work on the card payments platform stood out.\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"batch_id": "eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34",
"status": "ready",
"version": 3,
"source": "api",
"campaign": {
"id": "3f9a1c27-8e4b-4d2a-b6f0-7c1e5a9d2b84",
"name": "Senior Backend Engineer, Monzo"
},
"sender": {
"team_member_id": "7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20",
"name": "Riya Kapoor",
"from_email": "riya@acmetalent.com"
},
"job": {
"id": "b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13",
"title": "Senior Backend Engineer",
"pipeline_stage_id": "e4a0c3b7-1f5d-4a8e-9b2c-6d3f7a1e5c88",
"pipeline_stage": "Contacted"
},
"start": {
"mode": "scheduled",
"at": "2026-10-19T08:00:00.000Z",
"timezone": "Europe/London"
},
"created_by": {
"type": "api_key",
"id": "0d4b8f2e-6a1c-4e9b-b3d7-5f2a8c1e4b96",
"name": "Greenhouse sync"
},
"created_at": "2026-10-13T11:20:00.000Z",
"expires_at": "2026-10-14T11:24:10.000Z",
"started_at": null,
"progress": null,
"summary": {
"total": 5,
"preparing": 0,
"ready": 2,
"needs_input": 2,
"blocked": 1,
"excluded": 0,
"enrolled": 0,
"rejected_at_start": 0
},
"warnings": [
{
"code": "adds_to_job_pipeline",
"message": "2 people will be added to Senior Backend Engineer at Contacted.",
"details": {
"count": 2
}
},
{
"code": "contains_overrides",
"message": "Ana Ruiz is enrolled despite a do-not-contact or duplicate block.",
"details": {
"count": 1,
"names": [
"Ana Ruiz"
]
}
},
{
"code": "job_automation_will_run",
"message": "Moving people to this stage starts these automations: Notify hiring manager.",
"details": {
"automations": [
"Notify hiring manager"
]
}
}
],
"recipients": [
{
"recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21",
"person_id": "2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40",
"name": "Sam Patel",
"email": "sam@gmail.com",
"status": "ready",
"issues": [
{
"code": "enrolled_in_other_campaign",
"message": "Also in 'Q4 platform engineers' (running).",
"details": {
"campaigns": [
"Q4 platform engineers"
]
}
}
],
"overrides": [],
"override_reason": null,
"enrollment_id": null,
"first_email_estimated_at": "2026-10-19T08:00:00.000Z"
},
{
"recipient_id": "b2d4f6a8-3c5e-4a7b-9d1f-2e4a6c8b0d32",
"person_id": "6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73",
"name": "Tom Reed",
"email": "tom@reed.dev",
"status": "needs_input",
"issues": [
{
"code": "missing_variables",
"message": "Fill in or leave blank: personalization_line.",
"details": {
"variables": [
"personalization_line"
]
}
}
],
"overrides": [],
"override_reason": null,
"enrollment_id": null,
"first_email_estimated_at": null
},
{
"recipient_id": "c3e5a7b9-4d6f-4b8c-ae2a-3f5b7d9c1e43",
"person_id": "9c4f1a7e-2d8b-4e6c-b3a9-5f1d7c3e8b24",
"name": "Priya Shah",
"email": "priya@shah.io",
"status": "blocked",
"issues": [
{
"code": "unsubscribed",
"message": "Unsubscribed from your emails on 2 Sep 2026."
}
],
"overrides": [],
"override_reason": null,
"enrollment_id": null,
"first_email_estimated_at": null
},
{
"recipient_id": "d4f6b8ca-5e7a-4c9d-bf3b-4a6c8e0d2f54",
"person_id": "4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95",
"name": "Mark Chen",
"email": "mark.chen@gmail.com",
"status": "needs_input",
"issues": [
{
"code": "company_do_not_contact",
"message": "Works at Globex, which is marked do not contact. Override with a reason to include them.",
"details": {
"companies": [
"Globex"
]
}
},
{
"code": "likely_bounce",
"message": "This email looks risky and may bounce."
}
],
"overrides": [],
"override_reason": null,
"enrollment_id": null,
"first_email_estimated_at": null
},
{
"recipient_id": "e5a7c9db-6f8b-4dae-8c4d-5b7d9f1e3a65",
"person_id": "8f6c1d2e-3b5a-4c7e-9d1f-6a8c0e2b4d76",
"name": "Ana Ruiz",
"email": "ana.ruiz@gmail.com",
"status": "ready",
"issues": [
{
"code": "previously_in_campaign",
"message": "Was in this campaign before at ana.ruiz@gmail.com: enrolled 2 Sep 2026, then stopped.",
"details": {
"enrollment_id": "1c3e5a7b-8d9f-4a2c-b4e6-7f9a1c3e5b87",
"status": "stopped",
"enrolled_at": "2026-09-02T09:30:00.000Z"
}
}
],
"overrides": [
"company_do_not_contact"
],
"override_reason": "Their hiring manager asked us to reach out.",
"enrollment_id": null,
"first_email_estimated_at": "2026-10-19T08:00:00.000Z"
}
],
"sample": {
"recipient_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21",
"subject": "Senior Backend Engineer role at Monzo",
"body_text": "Hi Sam,\n\nYour work scaling payments at Wise stood out. I'm hiring a Senior Backend Engineer at Monzo. Loved your PyCon talk on async Python.\n\nYou can see the role here (https://jobs.stardex.com/acme-talent/senior-backend-engineer-k3f9a2). Open to a chat?\n\nRiya"
}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Authorizations
Authenticate with a Bearer token: API key, OAuth token, or session token.
Body
application/json
People to enroll, each person once. A batch holds up to your workspace's recipient limit (50 by default), and never more than 1,000.
Required array length:
1 - 1000 elementsShow child attributes
Show child attributes
Was this page helpful?