Skip to main content
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.
All endpoints should pass in the userId in the request body. You can find your userId in the sa.dialgen.ai dashboard.
  • Endpoint: POST /api/v1/batch
  • Method: POST
  • Request Body: 
    {
  "agentId": "agent_clx123abc...",
  "userId": "user_clx456def...",
  "contacts": [
    {
      "id": "contact_clx789xyz...",
      "phoneNumber": "+15551234567",
      "name": "Jane Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "metadata": { "lead_score": 80 }
    },
    {
      "phoneNumber": "+15557654321",
      "name": "John Smith",
      "email": "[email protected]",
      "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": {
      "onBatchComplete": "https://api.your-crm.com/webhook/dialgen/batch-complete",
      "onCallComplete": "https://api.your-crm.com/webhook/dialgen/call-complete",
      "onBatchFailed": "https://api.your-crm.com/webhook/dialgen/batch-failed"
    },
    "tags": ["Q4_campaign", "high_priority"]
  }
}

​
Request Parameters

  • agentId (string, required): The agent ID to use for the entire batch.
  • userId (string, required): The user ID owning the agent.
  • contacts (array, required): An array of contact objects (min: 1, max: 100,000 per batch). Contact Object Fields:
    • id (string, optional): If the contact already exists in your database, provide the existing contact ID. The system will:
      • Reuse the existing contact and preserve its call history
      • Update the contact to be part of this new batch
      • Reset attempt counts for the new campaign
      • Note: If both id and phoneNumber match an existing contact, the contact will be updated, not duplicated.
    • phoneNumber (string, required): E.164 formatted phone number (minimum 10 characters).
    • name (string, optional): Contact’s name (defaults to “Unknown”).
    • email (string, optional): Contact’s email address (must be valid email format if provided).
    • company (string, optional): Contact’s company name.
    • metadata (object, optional): Custom key-value pairs for additional contact information (e.g., lead score, account ID, custom fields).
  • options (object, optional): Batch processing configuration.
    • priority (number, optional): Priority level from 1-10 (default: 5). Higher priority batches are processed first.
    • scheduledStartTime (string, optional): ISO 8601 datetime string for scheduling the batch to start in the future. Must be a future time.
    • timezone (string, optional): Timezone for scheduling (default: “UTC”).
    • maxCallsPerSecond (number, optional): Rate limiting for calls (min: 1, max: 30, default: 10).
    • retryStrategy (object, optional): Configuration for retry logic.
      • maxAttempts (number, optional): Maximum retry attempts per contact (min: 1, max: 5, default: 3).
      • noAnswerDelay (number, optional): Delay in milliseconds before retrying a no-answer call (default: 3600000 = 1 hour).
      • busyDelay (number, optional): Delay in milliseconds before retrying a busy call (default: 300000 = 5 minutes).
    • webhooks (object, optional): Webhook URLs for event notifications.
      • onBatchComplete (string, optional): Called when the entire batch finishes processing.
      • onCallComplete (string, optional): Called after each individual call completes.
      • onBatchFailed (string, optional): Called if the batch fails.
    • tags (array of strings, optional): Tags for filtering and grouping batches.

​
Contact Deduplication & History Preservation

The batch API intelligently handles duplicate contacts to preserve call history:
  1. By Contact ID: If you provide an id that exists in the database for this agent, the existing contact record is reused and moved to the new batch.
  2. By Phone Number: If a phoneNumber matches an existing contact (normalized), the existing contact is reused.
  3. New Contacts: Only truly new contacts (no matching ID or phone number) are created.
  4. Batch Assignment: Existing contacts are automatically reassigned to the new batch with reset attempt counts, ensuring they’re included in the campaign without losing historical data.
Example Scenarios:
  • Scenario 1: You provide id: "contact_123" and it exists → Contact is moved to new batch, history preserved.
  • Scenario 2: You provide phoneNumber: "+15551234567" that exists → Contact is matched by phone, moved to new batch.
  • Scenario 3: You provide both id and phoneNumber that don’t exist → New contact is created.
  • Scenario 4: You provide id: "contact_123" but a different phoneNumber → Contact ID takes precedence, phone number is updated.
  • Success Response (202 Accepted): The server acknowledges the request. Use the returned batchId for monitoring. 
    {
  "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..."
  }
}
  • Error Responses: 400 Bad Request - Validation Failed: 
    {
  "error": "Validation failed",
  "code": "INVALID_REQUEST",
  "details": {
    "fieldErrors": {
      "contacts": ["At least one contact required"],
      "agentId": ["Agent ID is required"]
    }
  }
}
    400 Bad Request - Scheduled Time Invalid: 
    {
  "error": "Scheduled start time must be in the future"
}
    402 Payment Required - Insufficient Credits: 
    {
  "error": "Insufficient call minutes",
  "code": "INSUFFICIENT_CREDITS",
  "message": "Estimated 2000 minutes required, but only 500 available",
  "details": {
    "estimatedMinutesRequired": 2000,
    "availableMinutes": 500
  }
}
    404 Not Found - Agent Not Found: 
    {
  "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 Internal Server Error: 
    {
  "error": "Internal server error"
}

​
Batch Processing Workflow

When you submit a batch, the following process occurs:
  1. Validation (Immediate): Request is validated for required fields, contact format, and agent existence.
  2. Pre-flight Checks (Immediate):
    • Agent must exist and be active
    • User must have sufficient call minutes (estimated at 2 minutes per contact)
    • Scheduled start time must be in the future (if provided)
  3. Ingestion (Background): Contacts are processed in chunks of 500:
    • Existing contacts (by ID or phone number) are identified and moved to the new batch
    • New contacts are created in bulk
    • Duplicate contacts within the batch are automatically handled
    • Call history is preserved for existing contacts
  4. Scheduling (Background): Once ingestion completes:
    • If scheduledStartTime is provided, batch status becomes scheduled
    • Otherwise, batch processing begins immediately
  5. Processing (Background): Calls are initiated according to:
    • Priority level (higher priority batches first)
    • Rate limiting (maxCallsPerSecond)
    • Retry strategy for failed calls
Batch Status Lifecycle:
  • ingesting → Contacts are being added to the database
  • scheduled → Ingestion complete, waiting for scheduled start time
  • pending → Ready to start processing calls
  • processing → Actively making calls
  • completed → All calls finished