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

# Get Lead

> Retrieve a single lead with all its activities

<Warning>
  **Rate Limits:**

  * Request Rate: \~100 requests per 5 seconds per project (same as other lead APIs).
  * Heavy use of this endpoint (especially with `masked=false`) can be expensive; cache results when possible.
</Warning>

## Query Parameters

<ParamField query="leadId" type="string">
  MongoDB ObjectId of the lead (required if not using referenceId)
</ParamField>

<ParamField query="referenceId" type="string">
  External reference ID (requires projectId and processId)
</ParamField>

<ParamField query="projectId" type="string">
  Required when using referenceId
</ParamField>

<ParamField query="processId" type="string">
  Required when using referenceId
</ParamField>

<ParamField query="masked" type="boolean" default="false">
  If `true`, masks phone number (all but last 4 digits)
</ParamField>

## Response

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

<ResponseField name="data" type="object">
  The lead object with activities

  <Expandable title="Lead Properties">
    <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="lastDisposition" type="string">
      Last disposition
    </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>

    <ResponseField name="activities" type="array">
      Array of activity objects
    </ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

* **400 Bad Request**
  * **Missing identifier**
    * Returned when neither `leadId` nor `referenceId` is provided.
    * Example:
      ```json theme={null}
      {
        "success": false,
        "error": "Either leadId or referenceId is required"
      }
      ```
  * **Missing projectId/processId with referenceId**
    * Returned when `referenceId` is provided without both `projectId` and `processId`.
    * Example:
      ```json theme={null}
      {
        "success": false,
        "error": "projectId and processId are required when using referenceId"
      }
      ```

* **404 Not Found**
  * Returned when no lead matches the provided identifiers.
  * Examples:
    ```json theme={null}
    { "success": false, "error": "Lead with ID <leadId> not found" }
    { "success": false, "error": "Lead with referenceId <referenceId> not found" }
    ```

* **429 Too Many Requests**
  * Returned when project-level rate limits are exceeded for this endpoint.
  * Recommended behavior:
    * Back off and retry later with exponential backoff.
    * Avoid hot-loop polling; cache results on your side when possible.

* **500 Internal Server Error**
  * Unexpected server-side error.
  * Safe to retry with backoff; if it persists, contact support with request details.