> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get an enrollment batch
> The batch's people with their status and issues, warnings, one sample email, and the `version` and `summary.ready` to pass to start. Add `include=content` for every person's final steps. Needs `campaigns:read`.
## OpenAPI
````yaml /api-reference/openapi-v1.json get /v1/campaigns/{id}/enrollment-batches/{batch_id}
openapi: 3.1.0
info:
title: Stardex API (v1)
version: 1.0.0
description: >-
Stardex ATS API — manage candidates, jobs, companies, and recruiting
workflows.
servers:
- url: https://api.stardex.ai
description: Production API server
security:
- bearerAuth: []
tags:
- name: Persons
description: Manage person records — contacts, work history, and custom fields.
- name: Jobs
description: Manage job postings — pipeline stages, team members, and custom fields.
- name: Candidates
description: Manage candidate records and pipeline stage transitions.
- name: Companies
description: Browse and retrieve company records.
- name: Lists
description: Create, search, and retrieve saved person and company lists.
- name: Person Activities
description: Create and manage activity records (notes, emails, meetings) for persons.
- name: Team Members
description: List team members for use in search filters and assignments.
- name: Custom Fields
description: Retrieve custom field definitions and tag options for search filters.
- name: Campaigns
description: >-
Create and edit email campaigns, enroll people through enrollment batches,
and manage who is enrolled.
paths:
/v1/campaigns/{id}/enrollment-batches/{batch_id}:
get:
tags:
- Campaigns
summary: Get an enrollment batch
description: >-
The batch's people with their status and issues, warnings, one sample
email, and the `version` and `summary.ready` to pass to start. Add
`include=content` for every person's final steps. Needs
`campaigns:read`.
operationId: getCampaignEnrollmentBatch
parameters:
- schema:
type: string
format: uuid
description: Campaign ID.
required: true
description: Campaign ID.
name: id
in: path
- schema:
type: string
format: uuid
description: Enrollment batch ID.
required: true
description: Enrollment batch ID.
name: batch_id
in: path
- schema:
type: string
enum:
- content
description: 'content: also return every person''s final steps.'
required: false
description: 'content: also return every person''s final steps.'
name: include
in: query
responses:
'200':
description: Batch
content:
application/json:
schema:
$ref: '#/components/schemas/EnrollmentBatchResponse'
example:
success: true
data:
batch_id: eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34
status: ready
version: 2
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:20:40.000Z'
started_at: null
progress: null
summary:
total: 4
preparing: 0
ready: 1
needs_input: 2
blocked: 1
excluded: 0
enrolled: 0
rejected_at_start: 0
warnings:
- code: adds_to_job_pipeline
message: >-
1 person will be added to Senior Backend Engineer at
Contacted.
details:
count: 1
- 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'
steps:
- step_id: 5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43
order: 1
type: email
send_after_days: 0
subject: Senior Backend Engineer role at Monzo
body_html: >-
Hi Sam,
Your work
scaling payments at Wise stood out. I'm hiring a
Senior Backend Engineer at Monzo.
Loved your PyCon talk on async
Python.
You can see the
role
here.
Open to a chat?
Riya
edited: false
- step_id: 9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17
order: 2
type: email
send_after_days: 3
subject: 'Re: Senior Backend Engineer role at Monzo'
body_html: >-
Hi Sam, following up on my
note.
Riya
edited: false
- step_id: c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90
order: 3
type: manual
send_after_days: 2
subject: null
body_html: >-
Call Sam if they opened but did not
reply.
edited: false
- 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
steps:
- step_id: 5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43
order: 1
type: email
send_after_days: 0
subject: Senior Backend Engineer role at Monzo
body_html: >-
Hi Tom,
Your Kafka
migration at Deliveroo stood out. I'm hiring a
Senior Backend Engineer at Monzo.
{{personalization_line}}
You
can see the role
here.
Open to a chat?
Riya
edited: false
- step_id: 9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17
order: 2
type: email
send_after_days: 3
subject: 'Re: Senior Backend Engineer role at Monzo'
body_html: >-
Hi Tom, following up on my note. We placed 3
engineers at Monzo last
year.
Riya
edited: false
- step_id: c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90
order: 3
type: manual
send_after_days: 2
subject: null
body_html: >-
Call Tom if they opened but did not
reply.
edited: false
- 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
steps: []
- 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
steps:
- step_id: 5b0f3c8e-2a71-4d0e-9a51-6f0c2d7e1a43
order: 1
type: email
send_after_days: 0
subject: Senior Backend Engineer role at Monzo
body_html: >-
Hi Mark,
Leading the
ledger rebuild at Globex stood out. I'm hiring a
Senior Backend Engineer at Monzo.
Your QCon London talk was
great.
You can see the role
here.
Open to a chat?
Riya
edited: false
- step_id: 9d2e7a14-61c3-4b8f-8f0e-3a5c9b2d4e17
order: 2
type: email
send_after_days: 3
subject: 'Re: Senior Backend Engineer role at Monzo'
body_html: >-
Hi Mark, following up on my note. We placed 3
engineers at Monzo last
year.
Riya
edited: false
- step_id: c4a8e2f1-7b3d-4e6a-9c1f-2d8b5a7e3f90
order: 3
type: manual
send_after_days: 2
subject: null
body_html: >-
Call Mark if they opened but did not
reply.
edited: false
sample:
recipient_id: a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21
subject: Senior Backend Engineer role at Monzo
body_text: >-
Hi Sam,
Your work scaling payments at Wise stood out. I'm hiring a
Senior Backend Engineer at Monzo. Loved your PyCon talk on
async Python.
You can see the role here
(https://jobs.stardex.com/acme-talent/senior-backend-engineer-k3f9a2).
Open to a chat?
Riya
'400':
description: Validation error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
description: Always false for error responses.
error:
type: object
properties:
code:
type: string
description: >-
Machine-readable error code (e.g. "VALIDATION_ERROR",
"NOT_FOUND").
message:
type: string
description: Human-readable error description.
details:
type: object
additionalProperties: {}
description: >-
Extra facts about the error when they help you fix it,
such as a limit and when it resets.
required:
- code
- message
required:
- success
- error
'403':
description: No access to campaigns, or the API key lacks the permission
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
description: Always false for error responses.
error:
type: object
properties:
code:
type: string
description: >-
Machine-readable error code (e.g. "VALIDATION_ERROR",
"NOT_FOUND").
message:
type: string
description: Human-readable error description.
details:
type: object
additionalProperties: {}
description: >-
Extra facts about the error when they help you fix it,
such as a limit and when it resets.
required:
- code
- message
required:
- success
- error
'404':
description: Resource not found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
description: Always false for error responses.
error:
type: object
properties:
code:
type: string
description: >-
Machine-readable error code (e.g. "VALIDATION_ERROR",
"NOT_FOUND").
message:
type: string
description: Human-readable error description.
details:
type: object
additionalProperties: {}
description: >-
Extra facts about the error when they help you fix it,
such as a limit and when it resets.
required:
- code
- message
required:
- success
- error
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
description: Always false for error responses.
error:
type: object
properties:
code:
type: string
description: >-
Machine-readable error code (e.g. "VALIDATION_ERROR",
"NOT_FOUND").
message:
type: string
description: Human-readable error description.
details:
type: object
additionalProperties: {}
description: >-
Extra facts about the error when they help you fix it,
such as a limit and when it resets.
required:
- code
- message
required:
- success
- error
components:
schemas:
EnrollmentBatchResponse:
type: object
properties:
success:
type: boolean
enum:
- true
data:
$ref: '#/components/schemas/EnrollmentBatch'
required:
- success
- data
EnrollmentBatch:
type: object
properties:
batch_id:
type: string
format: uuid
status:
type: string
enum:
- preparing
- ready
- starting
- started
- discarded
- expired
description: >-
preparing: AI variables are being written. ready: can be edited and
started. starting: people are enrolled and adding them to the job or
as client contacts is still finishing. started, discarded, expired:
final.
version:
type: integer
description: Goes up with every change. Pass it to start.
source:
type: string
enum:
- api
- mcp
- copilot
- app
description: >-
Where the batch was made: api (an API key), mcp (an AI assistant
connected over MCP), copilot (Ask Dex) or app (a signed-in user
calling the API).
campaign:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
required:
- id
- name
sender:
type: object
properties:
team_member_id:
type: string
format: uuid
name:
type:
- string
- 'null'
from_email:
type: string
required:
- team_member_id
- name
- from_email
job:
type:
- object
- 'null'
properties:
id:
type: string
format: uuid
title:
type: string
pipeline_stage_id:
type:
- string
- 'null'
format: uuid
pipeline_stage:
type:
- string
- 'null'
required:
- id
- title
- pipeline_stage_id
- pipeline_stage
start:
type: object
properties:
mode:
type: string
enum:
- next_window
- now
- scheduled
at:
type:
- string
- 'null'
timezone:
type:
- string
- 'null'
required:
- mode
- at
- timezone
created_by:
type: object
properties:
type:
type: string
enum:
- api_key
- team_member
id:
type:
- string
- 'null'
format: uuid
name:
type:
- string
- 'null'
required:
- type
- id
- name
description: >-
Who prepared the batch: an API key, with its name, or a team member.
Only they can change, start or discard it.
created_at:
type: string
expires_at:
type: string
description: A draft expires 24 hours after its last change.
started_at:
type:
- string
- 'null'
progress:
type:
- object
- 'null'
properties:
done:
type: integer
total:
type: integer
required:
- done
- total
description: AI writing progress while preparing.
summary:
type: object
properties:
total:
type: integer
preparing:
type: integer
ready:
type: integer
needs_input:
type: integer
blocked:
type: integer
excluded:
type: integer
enrolled:
type: integer
rejected_at_start:
type: integer
required:
- total
- preparing
- ready
- needs_input
- blocked
- excluded
- enrolled
- rejected_at_start
warnings:
type: array
items:
type: object
properties:
code:
type: string
description: >-
exceeds_daily_capacity, daily_limit_reached (the mailbox
already sent its daily limit today and the first email is due
today, so it waits for the reset), sending_disabled,
mailbox_rate_limited, outside_sending_window,
adds_to_job_pipeline, creates_client_contacts,
contains_overrides (details has the names), shared_email (one
per email several people use; details has the email and the
names), job_automation_will_run or steps_without_timezone.
outside_sending_window means the first email goes out outside
sending hours, on a weekend or on a holiday the campaign skips
(start_mode now or scheduled), or has to wait for the next
sending window (next_window); details has reason
(outside_hours, weekend or holiday), sending_hours and
first_email_at.
message:
type: string
details:
type: object
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
- type: 'null'
- type: array
items:
type: string
- type: 'null'
description: Extra facts about the issue, such as variable names.
required:
- code
- message
recipients:
type: array
items:
type: object
properties:
recipient_id:
type: string
format: uuid
person_id:
type: string
format: uuid
name:
type:
- string
- 'null'
email:
type:
- string
- 'null'
status:
type: string
enum:
- preparing
- ready
- needs_input
- blocked
- excluded
- enrolled
- rejected_at_start
description: >-
ready: enrolled at start. needs_input and blocked: not
enrolled; see issues. excluded: left out by you. preparing: AI
variables are still being written. After start: enrolled or
rejected_at_start.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: >-
Blocks: person_not_found, email_bounced, unsubscribed,
person_do_not_contact, already_enrolled. Needs input:
no_email, email_not_on_person, company_do_not_contact,
already_enrolled_different_email, previously_completed,
missing_variables, ai_generation_failed. Warnings:
likely_bounce, enrolled_in_other_campaign,
previously_in_campaign (was in this campaign before and
was stopped, cancelled or failed).
message:
type: string
description: What is wrong and how to fix it.
details:
type: object
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
- type: 'null'
- type: array
items:
type: string
- type: 'null'
description: Extra facts about the issue, such as variable names.
required:
- code
- message
overrides:
type: array
items:
type: string
enum:
- company_do_not_contact
- duplicate_enrollment
description: Blocks this person is enrolled despite.
override_reason:
type:
- string
- 'null'
enrollment_id:
type:
- string
- 'null'
format: uuid
description: Set once enrolled.
first_email_estimated_at:
type:
- string
- 'null'
description: >-
Estimated time of this person's first email, following
start_mode and moved to later days when the batch is more than
the mailbox's daily limit can send. null when the person isn't
ready, the first step isn't an email, or the mailbox's daily
limit is 0.
steps:
type: array
items:
type: object
properties:
step_id:
type: string
format: uuid
description: Campaign step ID.
order:
type: integer
description: 1-based position in the campaign.
type:
type: string
enum:
- email
- manual
- text
- linkedin_message
- linkedin_connection
- call
send_after_days:
type: integer
subject:
type:
- string
- 'null'
body_html:
type: string
edited:
type: boolean
description: >-
Edited for this person, so variable changes don't
rewrite it.
required:
- step_id
- order
- type
- send_after_days
- subject
- body_html
- edited
description: Only with include=content.
required:
- recipient_id
- person_id
- name
- email
- status
- issues
- overrides
- override_reason
- enrollment_id
- first_email_estimated_at
sample:
type:
- object
- 'null'
properties:
recipient_id:
type: string
format: uuid
subject:
type:
- string
- 'null'
body_text:
type: string
required:
- recipient_id
- subject
- body_text
description: The first ready person's first email, as plain text.
required:
- batch_id
- status
- version
- source
- campaign
- sender
- job
- start
- created_by
- created_at
- expires_at
- started_at
- progress
- summary
- warnings
- recipients
- sample
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Authenticate with a Bearer token: API key, OAuth token, or session
token.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.