> ## Documentation Index > Fetch the complete documentation index at: https://docs.dialgen.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a New Call Batch (Campaign) > Submits a list of contacts to be called as a new campaign. The server accepts the job and begins ingesting the contacts in the background. ## OpenAPI ````yaml post /api/v1/batch openapi: 3.0.3 info: title: Dialgen API description: >- Dialgen API allows you to programmatically initiate and monitor AI-powered voice calls, either one at a time or in high-volume batches. version: 1.0.0 contact: name: Dialgen Support url: https://sa.dialgen.ai servers: - url: https://sa.dialgen.ai description: Production server security: - bearerAuth: [] tags: - name: Agents description: Operations related to AI agents - name: Calls description: Operations related to individual calls - name: Batches description: Operations related to batch campaigns paths: /api/v1/batch: post: tags: - Batches summary: Create a New Call Batch (Campaign) description: >- Submits a list of contacts to be called as a new campaign. The server accepts the job and begins ingesting the contacts in the background. operationId: createBatch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBatchRequest' example: agentId: agent_clx123abc... userId: user_clx456def... contacts: - id: contact_clx789xyz... phoneNumber: '+15551234567' name: Jane Doe email: jane@example.com company: Acme Corp metadata: lead_score: 80 - phoneNumber: '+15557654321' name: John Smith email: john@example.com company: null metadata: account_id: A123 options: priority: 5 scheduledStartTime: '2025-11-16T09:00:00.000Z' timezone: UTC maxCallsPerSecond: 10 retryStrategy: maxAttempts: 3 noAnswerDelay: 3600000 busyDelay: 300000 webhooks: onCallComplete: https://api.your-crm.com/webhook/dialgen/call-complete tags: - Q4_campaign - high_priority responses: '202': description: Batch accepted and is being processed content: application/json: schema: $ref: '#/components/schemas/CreateBatchResponse' example: success: true batchId: batch_1678886400_agent_clx123... status: ingesting message: >- Batch accepted and is being processed. Monitor the status link for updates. links: status: >- https://sa.dialgen.ai/api/v1/batch/batch_1678886400_agent_clx123.../status dashboard: >- https://sa.dialgen.ai/batch/monitor/batch_1678886400_agent_clx123... '400': description: Validation failed or scheduled time invalid content: application/json: schema: $ref: '#/components/schemas/Error' examples: validationFailed: value: error: Validation failed code: INVALID_REQUEST details: fieldErrors: contacts: - At least one contact required agentId: - Agent ID is required scheduledTimeInvalid: value: error: Scheduled start time must be in the future '401': $ref: '#/components/responses/Unauthorized' '402': description: Insufficient call minutes content: application/json: schema: type: object properties: error: type: string code: type: string message: type: string details: type: object properties: estimatedMinutesRequired: type: number availableMinutes: type: number example: error: Insufficient call minutes code: INSUFFICIENT_CREDITS message: Estimated 2000 minutes required, but only 500 available details: estimatedMinutesRequired: 2000 availableMinutes: 500 '404': description: Agent not found or inactive content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Agent not found or inactive code: AGENT_NOT_FOUND message: >- The specified agent does not exist, is inactive, or you do not have access to it '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreateBatchRequest: type: object required: - agentId - userId - contacts properties: agentId: type: string description: The agent ID to use for the entire batch userId: type: string description: The user ID owning the agent contacts: type: array minItems: 1 maxItems: 100000 items: $ref: '#/components/schemas/Contact' options: $ref: '#/components/schemas/BatchOptions' CreateBatchResponse: type: object properties: success: type: boolean batchId: type: string status: type: string enum: - ingesting - scheduled - pending - processing - completed message: type: string links: type: object properties: status: type: string format: uri dashboard: type: string format: uri Error: type: object properties: error: type: string code: type: string message: type: string details: type: object Contact: type: object required: - phoneNumber properties: id: type: string description: >- If the contact already exists in your database, provide the existing contact ID phoneNumber: type: string minLength: 10 description: E.164 formatted phone number name: type: string description: Contact's name (defaults to 'Unknown') email: type: string format: email description: Contact's email address company: type: string description: Contact's company name metadata: type: object additionalProperties: true description: Custom key-value pairs for additional contact information BatchOptions: type: object properties: priority: type: number minimum: 1 maximum: 10 default: 5 description: >- Priority level from 1-10. Higher priority batches are processed first scheduledStartTime: type: string format: date-time description: >- ISO 8601 datetime string for scheduling the batch to start in the future timezone: type: string default: UTC description: Timezone for scheduling maxCallsPerSecond: type: number minimum: 1 maximum: 30 default: 10 description: Rate limiting for calls retryStrategy: $ref: '#/components/schemas/RetryStrategy' webhooks: $ref: '#/components/schemas/Webhooks' tags: type: array items: type: string description: Tags for filtering and grouping batches RetryStrategy: type: object properties: maxAttempts: type: number minimum: 1 maximum: 5 default: 3 description: Maximum retry attempts per contact noAnswerDelay: type: number default: 3600000 description: >- Delay in milliseconds before retrying a no-answer call (default: 1 hour) busyDelay: type: number default: 300000 description: >- Delay in milliseconds before retrying a busy call (default: 5 minutes) Webhooks: type: object properties: onBatchComplete: type: string format: uri description: Called when the entire batch finishes processing onCallComplete: type: string format: uri description: Called after each individual call completes onBatchFailed: type: string format: uri description: Called if the batch fails responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized message: Invalid or missing API key InternalServerError: description: An unexpected server error occurred content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Internal Server Error message: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Bearer token authentication. Obtain your API key from the Dialgen API Keys dashboard at https://sa.dialgen.ai/api-keys ````