> ## 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.

# Initiate Lead

> Create or validate a lead and optionally start initialization for calling

<Warning>
  **Rate Limits:**

  * Request Rate: \~100 requests per 5 seconds per project
  * Duplicate Detection: More than 5 duplicate submissions in 60 seconds will block the API key for 60 minutes
</Warning>

## Body Parameters

<ParamField body="leadId" type="string">
  Existing lead ID to validate (required if `lead` not provided)
</ParamField>

<ParamField body="lead" type="object">
  New lead object (required if `leadId` 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 for tracking
    </ParamField>

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

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

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="_id" type="string">
  MongoDB ObjectId of the lead
</ResponseField>

<ResponseField name="name" type="string">
  Lead's name
</ResponseField>

<ResponseField name="phone" type="string">
  Phone number
</ResponseField>

<ResponseField name="email" type="string">
  Email address
</ResponseField>

<ResponseField name="projectId" type="string">
  Project ID
</ResponseField>

<ResponseField name="processId" type="string">
  Process ID
</ResponseField>

<ResponseField name="referenceId" type="string">
  External reference ID
</ResponseField>

<ResponseField name="currentState" type="string">
  Current state of the lead
</ResponseField>

<ResponseField name="metadata" type="object">
  Lead metadata
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of creation
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of last update
</ResponseField>

## Error Responses

* **400 Bad Request**
  * **Missing body**
    * Returned when neither `leadId` nor `lead` is provided.
    * Example: `{ "error": "Either leadId or lead object is required" }`
  * **Missing projectId**
    * Returned when creating a new lead without `lead.projectId`.
    * Example: `{ "error": "projectId is required in lead object" }`
  * **Validation errors / bad leads**
    * Returned when the lead fails validation during creation or duplicate checks.
    * 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 a bad/invalid lead. Do not retry these leads via this API.**
    * Recommended behavior:
      * Mark the lead as invalid in your system.
      * Fix the underlying data (phone number, process, etc.) before attempting again as a new lead.

* **403 Forbidden**
  * Returned when `lead.projectId` does not match the authenticated project for the API key.
  * Example: `{ "error": "projectId does not match authenticated project" }`

* **429 Too Many Requests**
  * Returned when duplicate protection blocks the API key due to too many duplicate submissions.
  * Example response: `{ "success": false, "error": "...temporarily blocked..." }`
  * **Do not retry the same bad/duplicate leads.**
  * Recommended behavior:
    * Stop sending further requests from the offending source.
    * Investigate and fix the duplication issue before resuming traffic.

* **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 400 response with validation/duplicate messages (as above) should be treated as a permanent failure for that payload.
  * Re-sending the same bad lead can:
    * Trigger duplicate-protection rate 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.