> ## 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. # Prepare an enrollment > Creates a draft enrollment batch: checks every person, fills their variables and writes each person's final emails. Nothing is enrolled or sent until you call start. Each person comes back `ready`, `needs_input` or `blocked` with the reasons in `issues`; fix people with `PATCH .../recipients/{recipient_id}`. When the campaign uses AI variables the batch is `preparing` while they are written; read it again until it is `ready`. A draft expires 24 hours after its last change. With API keys, MCP and Ask Dex together, a workspace can enroll up to 500 people in 24 hours by default (`429 DAILY_ENROLLMENT_LIMIT_REACHED`). Needs `campaigns:enroll`. Signed-in users need access to campaigns in their role. API keys need the campaigns permission named on each endpoint. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/campaigns/{id}/enrollment-batches 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: post: tags: - Campaigns summary: Prepare an enrollment description: >- Creates a draft enrollment batch: checks every person, fills their variables and writes each person's final emails. Nothing is enrolled or sent until you call start. Each person comes back `ready`, `needs_input` or `blocked` with the reasons in `issues`; fix people with `PATCH .../recipients/{recipient_id}`. When the campaign uses AI variables the batch is `preparing` while they are written; read it again until it is `ready`. A draft expires 24 hours after its last change. With API keys, MCP and Ask Dex together, a workspace can enroll up to 500 people in 24 hours by default (`429 DAILY_ENROLLMENT_LIMIT_REACHED`). Needs `campaigns:enroll`. Signed-in users need access to campaigns in their role. API keys need the campaigns permission named on each endpoint. operationId: createCampaignEnrollmentBatch parameters: - schema: type: string format: uuid description: Campaign ID. required: true description: Campaign ID. name: id in: path requestBody: content: application/json: schema: $ref: '#/components/schemas/EnrollmentBatchCreateRequest' example: sender_team_member_id: 7c1e4a9b-3d6f-4b2e-8a5c-9f1d3b7e5a20 from_email: riya@acmetalent.com job_id: b21d7e4a-5c9f-4e3b-a1d6-8f2c4e7b9a13 job_pipeline_stage_id: e4a0c3b7-1f5d-4a8e-9b2c-6d3f7a1e5c88 start_mode: scheduled start_at: '2026-10-19T09:00:00' start_timezone: Europe/London variable_values: custom: We placed 3 engineers at Monzo last year. recipients: - person_id: 2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40 variable_values: personalization_line: Loved your PyCon talk on async Python. blank_variables: - custom - person_id: 6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73 - person_id: 9c4f1a7e-2d8b-4e6c-b3a9-5f1d7c3e8b24 - person_id: 4e8b2d6f-1a3c-4e9b-8f5d-7c2a6e1b3d95 variable_values: personalization_line: Your QCon London talk was great. responses: '201': description: Batch prepared content: application/json: schema: $ref: '#/components/schemas/EnrollmentBatchResponse' example: success: true data: batch_id: eb8d2f41-3c7a-4e19-b5d2-7f0a1c9e6b34 status: preparing version: 1 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:00.000Z' started_at: null progress: done: 1 total: 4 summary: total: 4 preparing: 3 ready: 0 needs_input: 0 blocked: 1 excluded: 0 enrolled: 0 rejected_at_start: 0 warnings: [] recipients: - recipient_id: a1c3e5f7-2b4d-4f6a-8c0e-1d3f5b7a9c21 person_id: 2f6b9d1e-4a8c-4e3f-b7d2-1c5a9e3b7f40 name: Sam Patel email: sam@gmail.com status: preparing 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: null - recipient_id: b2d4f6a8-3c5e-4a7b-9d1f-2e4a6c8b0d32 person_id: 6a3e8c2f-9b1d-4f7a-a5c3-8e2b6d4f1a73 name: Tom Reed email: tom@reed.dev status: preparing issues: [] 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: preparing 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 sample: null '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 campaign is archived or has no steps, or the mailbox is disconnected (CAMPAIGN_ARCHIVED, CAMPAIGN_HAS_NO_STEPS, MAILBOX_DISCONNECTED) 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 '429': description: >- Daily enrollment limit reached (DAILY_ENROLLMENT_LIMIT_REACHED), or rate limited (RATE_LIMIT_EXCEEDED) 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: EnrollmentBatchCreateRequest: type: object properties: sender_team_member_id: type: string format: uuid description: >- Team member the emails are sent as. Required with an API key; signed-in users always send as themselves. from_email: type: string format: email description: >- Mailbox to send from: the sender's own or one shared with them. See GET /v1/campaigns/mailboxes. job_id: type: - string - 'null' format: uuid description: >- Job to add everyone to, which also fills {{search_name}}, {{search_client}} and {{application_link}}. job_pipeline_stage_id: type: - string - 'null' format: uuid description: >- Pipeline stage of job_id to put everyone in. Left out, people already on the job keep their stage and new ones start in the job's first stage. start_mode: type: string enum: - next_window - now - scheduled default: next_window description: >- next_window (default): the first step's wait counts from now, then the email goes out in its next sending window, skipping weekends and holidays the campaign doesn't send on. now: the first email goes out right away, even outside sending hours, on a weekend or holiday, or when the first step has a wait. scheduled: the first email goes out at start_at in start_timezone, even outside sending hours or on a weekend or holiday; if the first step has a wait, it counts from start_at and the email then goes out in the next sending window. The outside_sending_window warning tells you when the first email goes out off schedule or has to wait. start_at: type: - string - 'null' description: >- When to start, only with start_mode scheduled: a local date and time such as 2026-10-19T09:00:00, read in start_timezone, 5 minutes to 90 days ahead. A batch's timing can't be changed after it is prepared; to move it, discard the batch and prepare a new one. start_timezone: type: - string - 'null' description: >- IANA timezone for start_at, for example Europe/London. Required with start_mode scheduled. email_preference: type: string enum: - auto - work - personal default: auto description: >- Which email to pick for people without one given. auto: work emails for business development and client nurture campaigns, personal emails otherwise. The person's preferred email always wins. variable_values: type: object additionalProperties: type: string maxLength: 2000 description: >- Values used for everyone in the batch. A person's own variable_values win. blank_variables: type: array items: type: string minLength: 1 maxLength: 100 maxItems: 100 description: Variables to leave out for everyone in the batch. override_reason: type: - string - 'null' minLength: 1 maxLength: 1000 description: Reason used for every person with overrides and no own reason. recipients: type: array items: $ref: '#/components/schemas/EnrollmentBatchRecipientInput' minItems: 1 maxItems: 1000 description: >- 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: - from_email - recipients EnrollmentBatchResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/EnrollmentBatch' required: - success - data EnrollmentBatchRecipientInput: type: object properties: person_id: type: string format: uuid description: Person to enroll. email: type: - string - 'null' format: email description: >- Email to send to. Left out, the person's best email is picked using email_preference. 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 for {{variables}}, keyed by the name used in the template, for example {"personalization_line": "Loved your PyCon talk."} or {"ai:opening_line": "..."} to write an AI variable yourself. blank_variables: type: array items: type: string minLength: 1 maxLength: 100 maxItems: 100 description: >- Variables to leave out of the email. The {{token}} is removed and the spacing around it tidied. 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. required: - person_id 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.