> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uservox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Initiate Leads

> Create or validate multiple leads in a single request and optionally start initialization

<Warning>
  **Rate Limits:**

  * Request Rate: \~100 requests per 5 seconds per project
  * Maximum Leads: 1000 leads per request
</Warning>

## Body Parameters

<ParamField body="leadIds" type="string[]">
  Array of existing lead IDs (required if `leads` not provided)
</ParamField>

<ParamField body="leads" type="object[]">
  Array of new lead objects (required if `leadIds` not provided)

  <Expandable title="Lead Object Properties">
    <ParamField body="projectId" type="string" required>
      MongoDB ObjectId of the project
    </ParamField>

    <ParamField body="processId" type="string" required>
      MongoDB ObjectId of the process
    </ParamField>

    <ParamField body="groupId" type="string">
      Optional ID to group leads for analytics
    </ParamField>

    <ParamField body="phone" type="string">
      Phone number (required if email not provided)
    </ParamField>

    <ParamField body="email" type="string">
      Email address (required if phone not provided)
    </ParamField>

    <ParamField body="name" type="string">
      Full name (required if firstName not provided)
    </ParamField>

    <ParamField body="firstName" type="string">
      First name (required if name not provided)
    </ParamField>

    <ParamField body="lastName" type="string">
      Last name
    </ParamField>

    <ParamField body="referenceId" type="string">
      External reference ID
    </ParamField>

    <ParamField body="metadata" type="object">
      Additional metadata
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="init" type="boolean" default="true">
  Whether to initialize leads for calling
</ParamField>

## Query Parameters

<ParamField query="v" type="string">
  API version. Use `"1.2"` for simplified response format
</ParamField>

## Response

<ResponseField name="success" type="array">
  Array of successfully created/validated leads
</ResponseField>

<ResponseField name="errors" type="array">
  Array of errors for leads that failed validation

  <Expandable title="Error Object Properties">
    <ResponseField name="data" type="object">
      The lead data that failed (default format)
    </ResponseField>

    <ResponseField name="referenceId" type="string">
      Reference ID of failed lead (v1.2 format)
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message
    </ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

* **400 Bad Request**
  * **Missing body / wrong type**
    * Returned when neither `leadIds` nor `leads` is provided, or when the value is not an array.
    * Examples:
      * `{ "error": "Either leadIds or leads array is required" }`
      * `{ "error": "Input must be an array" }`
  * **Too many leads**
    * Returned when the number of items exceeds the maximum per request.
    * Example: `{ "error": "Maximum of 1000 leads allowed per request" }` (limit may be overridden by config).
  * **Per-lead validation errors / bad leads**
    * Individual leads that fail validation (duplicate, bad phone, etc.) are reported in the `errors` array.
    * Typical messages include:
      * `"A call attempt has already been made to this phone number for this project"`
      * `"Phone number contains repeating digits pattern"`
      * `"already exists for this project and process"`
    * **These indicate bad/invalid leads. Do not retry these specific leads via this API.**
    * Recommended behavior:
      * Mark those leads as invalid in your system.
      * Fix the underlying data (phone number, process, etc.) before attempting again as new leads.

* **403 Forbidden**
  * Returned when some leads have missing or invalid `projectId` relative to the authenticated project.
  * Example:
    ```json theme={null}
    {
      "error": "Some leads have missing or invalid projectId",
      "invalidLeads": [
        { "data": { ... }, "error": "missing projectId" },
        { "data": { ... }, "error": "projectId does not match authenticated project" }
      ]
    }
    ```
  * Also returned when the target project is inactive or not found.

* **404 Not Found**
  * Returned when a `processId` in the `leads` array does not exist.
  * Example: `{ "error": "Process not found for lead with processId: <id>" }`

* **429 Too Many Requests**
  * Bulk initiate uses the same project-level rate limiting and duplicate protection as the single-lead initiate API.
  * If you continuously send duplicate or bad data, your API key may be temporarily blocked.
  * **Do not keep retrying the same bad leads**, as this can cause more 429s and longer blocks.

* **500 Internal Server Error**
  * Unexpected server-side error.
  * Safe to retry with exponential backoff **only** for 5xx responses (not for 4xx).

## Retry Guidance

* **Do not retry bad leads**
  * Any per-lead validation/duplicate errors returned in the `errors` array should be treated as permanent failures for those payloads.
  * Re-sending the same bad lead can:
    * Trigger duplicate-protection limits.
    * Lead to `429` blocks for your API key.
* **When to retry**
  * It is acceptable to implement retries (with backoff) for:
    * Network errors.
    * 5xx responses (`500` and other server errors).
  * Do **not** automatically retry on 4xx responses; fix the request or underlying data instead.