> ## Documentation Index > Fetch the complete documentation index at: https://docs.heymilo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bulk ingest candidates > Submit multiple candidates at once for processing through the interviewer's workflow. Returns an interview ID and URL for each candidate. ## OpenAPI ````yaml https://api.heymilo.ai/openapi.json post /api/v2/postings/{posting_id}/candidates/bulk openapi: 3.1.0 info: title: HeyMilo Public API description: >- External developer-facing API for HeyMilo. Create interviewers with agentic workflows, ingest candidates, retrieve interview results, and manage workspace resources. version: 2.0.0 servers: - url: https://api.heymilo.ai description: Production security: - ApiKeyAuth: [] tags: - name: Interviewers description: >- Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow. - name: Candidates description: >- Ingest candidates into an interviewer's workflow (sync or async, single or bulk) and list candidates with their progress. - name: Interviews description: >- Retrieve full interview results (scorecard, transcript, resume evaluation) and manage per-interview metadata. - name: Webhooks description: >- Register, list, and manage webhook endpoints that receive real-time event notifications. - name: Voices description: Browse the workspace voice registry for AI interviewer voices. - name: Phone Numbers description: List provisioned phone numbers for SMS and voice agents. - name: Sender Emails description: Manage sender email addresses used for candidate communications. - name: Email Templates description: View email templates configured for candidate outreach. - name: Email Template Groups description: View grouped email template configurations. - name: Design Templates description: View design templates that control the candidate interview UI. - name: Design Template Groups description: View grouped design template configurations. - name: Interview Templates description: >- View interview templates, reusable agent configurations cloned from a blueprint posting (workflow, questions, criteria, agent settings). - name: Domains description: Manage custom domains for white-labelled interview URLs. - name: Questions description: >- Create, read, update, delete, and reorder questions and criteria for an interviewer's workflow. Covers all modalities: voice, sms, form, resume_eligibility, resume_scoring, and voice_tags. - name: Workspaces description: >- List the workspaces accessible to the authenticated caller. API-key callers receive a single entry; OAuth callers receive every workspace they are a member of. paths: /api/v2/postings/{posting_id}/candidates/bulk: post: tags: - Candidates summary: Bulk ingest candidates description: >- Submit multiple candidates at once for processing through the interviewer's workflow. Returns an interview ID and URL for each candidate. operationId: ingestCandidatesBulk parameters: - name: posting_id in: path required: true schema: type: string title: Posting Id - name: X-API-KEY in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key - name: Authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Workspace-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Workspace-Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkCandidateIngestRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: >- #/components/schemas/SingleResponse_list_BulkIngestCandidateResponseItem__ '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' components: schemas: BulkCandidateIngestRequest: properties: data: items: $ref: '#/components/schemas/CandidateIngestRequest' type: array minItems: 1 title: Data description: List of candidates to ingest type: object required: - data title: BulkCandidateIngestRequest SingleResponse_list_BulkIngestCandidateResponseItem__: properties: data: items: $ref: '#/components/schemas/BulkIngestCandidateResponseItem' type: array title: Data meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta description: Optional metadata. Shape varies by endpoint. type: object required: - data title: SingleResponse[list[BulkIngestCandidateResponseItem]] APIErrorResponse: properties: error: $ref: '#/components/schemas/APIError' type: object required: - error title: APIErrorResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError CandidateIngestRequest: properties: name: type: string title: Name description: Candidate full name examples: - Jane Doe email: type: string title: Email description: Candidate email address examples: - jane.doe@example.com phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: Candidate phone number (E.164 format) examples: - '+12065551234' metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: >- Set of key-value pairs for storing additional information on the candidate. Up to 50 keys, each key max 40 chars, each value max 500 chars. examples: - ats_stage: phone_screen external_id: candidate_xyz data: anyOf: - additionalProperties: true type: object - type: 'null' title: Data description: Additional candidate data type: object required: - name - email title: CandidateIngestRequest BulkIngestCandidateResponseItem: properties: object: type: string const: candidate title: Object description: Object type identifier. default: candidate interview_id: type: string title: Interview Id description: Unique interview identifier for this candidate-posting pair. examples: - D536A69A4090E13F interview_url: type: string title: Interview Url description: URL the candidate uses to access the interview. examples: - https://candidates.heymilo.io/acme/i/D536A69A4090E13F metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: >- Set of key-value pairs for storing additional information. Up to 50 keys, each key max 40 chars, each value max 500 chars. examples: - ats_stage: phone_screen external_id: candidate_xyz type: object required: - interview_id - interview_url title: BulkIngestCandidateResponseItem description: A single item in the bulk ingest response. APIError: properties: type: type: string title: Type description: Error category examples: - invalid_request_error code: type: string title: Code description: Machine-readable error code examples: - validation_error message: type: string title: Message description: Human-readable summary examples: - The request body failed validation param: anyOf: - type: string - type: 'null' title: Param description: Top-level parameter that caused the error doc_url: anyOf: - type: string - type: 'null' title: Doc Url description: Link to relevant documentation errors: items: $ref: '#/components/schemas/APIErrorDetail' type: array title: Errors description: Detailed per-field validation errors type: object required: - type - code - message title: APIError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError APIErrorDetail: properties: code: type: string title: Code description: Machine-readable error code examples: - invalid_param message: type: string title: Message description: Human-readable explanation examples: - title must be between 3 and 200 characters param: anyOf: - type: string - type: 'null' title: Param description: Parameter that caused the error examples: - title type: object required: - code - message title: APIErrorDetail securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: API key for authentication. Pass your key in the X-API-KEY header. ````