> ## 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.
# Change one person in a batch
> Change the email, fill in or leave out variables, override a do-not-contact or duplicate block with a reason, set the final text of their steps, or exclude them. The person is checked again and comes back with their new status. Raises the batch `version`. Changes to different people can be sent at the same time; send all changes to one person in one request, since two at once return `409 BATCH_VERSION_CHANGED`. Only the API key or person who created the batch can change it. Needs `campaigns:enroll`.
## OpenAPI
````yaml /api-reference/openapi-v1.json patch /v1/campaigns/{id}/enrollment-batches/{batch_id}/recipients/{recipient_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}/recipients/{recipient_id}:
patch:
tags:
- Campaigns
summary: Change one person in a batch
description: >-
Change the email, fill in or leave out variables, override a
do-not-contact or duplicate block with a reason, set the final text of
their steps, or exclude them. The person is checked again and comes back
with their new status. Raises the batch `version`. Changes to different
people can be sent at the same time; send all changes to one person in
one request, since two at once return `409 BATCH_VERSION_CHANGED`. Only
the API key or person who created the batch can change it. Needs
`campaigns:enroll`.
operationId: updateCampaignEnrollmentBatchRecipient
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
format: uuid
description: The person's recipient_id in the batch (not their person_id).
required: true
description: The person's recipient_id in the batch (not their person_id).
name: recipient_id
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnrollmentBatchRecipientUpdateRequest'
example:
blank_variables:
- custom
responses:
'200':
description: Person updated
content:
application/json:
schema:
$ref: '#/components/schemas/EnrollmentBatchRecipientResponse'
example:
success: true
data:
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
enrollment_id: null
first_email_estimated_at: '2026-10-19T08:00:00.000Z'
add_email_to_person: false
overrides: []
override_reason: null
blank_variables:
- custom
variables:
first_name:
value: Sam
source: person
search_name:
value: Senior Backend Engineer
source: job
search_client:
value: Monzo
source: job
application_link:
value: >-
https://jobs.stardex.com/acme-talent/senior-backend-engineer-k3f9a2
source: job
sender_first_name:
value: Riya
source: sender
personalization_line:
value: Loved your PyCon talk on async Python.
source: provided
ai:opening_line:
value: Your work scaling payments at Wise stood out.
source: ai
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
'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
'409':
description: >-
The batch is preparing, has started or was discarded, or another
change to it landed first (BATCH_PREPARING, BATCH_NOT_EDITABLE,
BATCH_VERSION_CHANGED)
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
'410':
description: The draft expired 24 hours after its last change (BATCH_EXPIRED)
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:
EnrollmentBatchRecipientUpdateRequest:
type: object
properties:
email:
type: string
format: email
description: Send to this email instead.
add_email_to_person:
type: boolean
description: >-
Save email to the person's profile when it isn't one of their
emails. A batch can't send to an address without saving it, so
without this an email not on the profile leaves the person
needs_input (email_not_on_person).
variable_values:
type: object
additionalProperties:
type: string
maxLength: 2000
description: >-
Values to set for this person, merged into the ones already given.
An empty string removes a value.
blank_variables:
type: array
items:
type: string
minLength: 1
maxLength: 100
maxItems: 100
description: >-
Variables to leave out for this person, dropping any value given for
them. Replaces the list already given.
overrides:
type: array
items:
type: string
enum:
- company_do_not_contact
- duplicate_enrollment
maxItems: 2
description: >-
Enroll despite these blocks: company_do_not_contact (works at a
company marked do not contact) or duplicate_enrollment (already in
this campaign at another email, or finished it before). Needs
override_reason here or on the batch. Ignored when the person has
neither block. A blocked person (unsubscribed, bounced, marked do
not contact, or still in this campaign at the same email) cannot be
overridden, and passing overrides for them fails the whole request
with OVERRIDE_NOT_ALLOWED. To re-enroll someone at the same email,
stop their enrollment first.
override_reason:
type:
- string
- 'null'
minLength: 1
maxLength: 1000
description: Why the block is being overridden. Stored on the enrollment.
steps:
type: array
items:
type: object
properties:
step_id:
type: string
format: uuid
description: Campaign step ID.
subject:
type:
- string
- 'null'
maxLength: 998
description: >-
Only the first email step has its own subject. Later email
steps reply in its thread as "Re: ", so a
different subject on them is rejected; changing the first
subject renames them too.
body_html:
type: string
maxLength: 100000
required:
- step_id
maxItems: 20
description: >-
Final text for this person's steps, with no {{variables}} left.
Edited steps keep this text even when variables change.
excluded:
type: boolean
description: Leave this person out of the batch, or put them back.
EnrollmentBatchRecipientResponse:
type: object
properties:
success:
type: boolean
enum:
- true
data:
$ref: '#/components/schemas/EnrollmentBatchRecipient'
required:
- success
- data
EnrollmentBatchRecipient:
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.
add_email_to_person:
type: boolean
blank_variables:
type: array
items:
type: string
variables:
type: object
additionalProperties:
type: object
properties:
value:
type: string
source:
type: string
enum:
- person
- sender
- job
- provided
- provided_for_batch
- ai
required:
- value
- source
description: Every filled variable and where its value came from.
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
required:
- recipient_id
- person_id
- name
- email
- status
- issues
- overrides
- override_reason
- enrollment_id
- first_email_estimated_at
- add_email_to_person
- blank_variables
- variables
- steps
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.