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

# Update Lead Status

> Update a lead's status and queue it for conversion processing.

Updates a lead's status by assigning it a conversion label. The lead is then queued for processing, which sends the conversion to your connected ad platforms (Google Ads, Meta, etc.).

## Identifying a lead

You can identify the lead to update using any one of the following fields. At least one is required. If multiple are provided, the following priority order is used:

1. `leadId`
2. `uniqueIdentifier`
3. `email`
4. `phone`

Only the highest-priority identifier is used — the others are ignored.

## Request body

<ParamField body="leadId" type="number">
  The numeric ID of the lead to update.
</ParamField>

<ParamField body="email" type="string">
  Look up the lead by email address.
</ParamField>

<ParamField body="phone" type="string">
  Look up the lead by phone number.
</ParamField>

<ParamField body="uniqueIdentifier" type="string">
  Look up the lead by its user-provided unique identifier (e.g. your CRM lead ID).
</ParamField>

<ParamField body="conversionId" type="string" required>
  The conversion label to apply. Use a **conversion label ID** (UUID) from your project's conversion labels, or one of the special values:

  * `"open"` — reset the lead to open status (no job is queued)
  * `"lost"` — mark the lead as lost (queued for processing)

  You can find your conversion label IDs in the [LeadTrackr Dashboard](https://app.leadtrackr.io) under **Settings > Conversion Labels**. Each label has a unique UUID that you can copy and use as the `conversionId`. For more details on setting up conversion labels, see the [Conversion Labels guide](/conversion-labels/set-up-conversion-labels).
</ParamField>

<ParamField body="price" type="number">
  Lead value in **cents** (e.g. `5000` for \$50.00). Must be a non-negative number. If provided, the lead's price is updated before processing.
</ParamField>

<Note>
  At least one lead identifier (`leadId`, `email`, `phone`, or `uniqueIdentifier`) is required. The `leadId` field is no longer the only way to identify a lead.
</Note>

## Response

The response varies depending on the `conversionId` value. All responses include `uniqueIdentifier` alongside `leadId`.

### When `conversionId` is `"open"`

<ResponseField name="message" type="string">
  `"Lead status updated to open"`.
</ResponseField>

<ResponseField name="leadId" type="number">
  The ID of the updated lead.
</ResponseField>

<ResponseField name="uniqueIdentifier" type="string | null">
  The unique identifier for the lead, or `null` if not set.
</ResponseField>

<ResponseField name="status" type="string">
  `"open"`.
</ResponseField>

<ResponseField name="queued" type="boolean">
  `false` — no job is queued for open status.
</ResponseField>

### When `conversionId` is a conversion label or `"lost"`

<ResponseField name="message" type="string">
  `"Lead queued for processing"`.
</ResponseField>

<ResponseField name="leadId" type="number">
  The ID of the updated lead.
</ResponseField>

<ResponseField name="uniqueIdentifier" type="string | null">
  The unique identifier for the lead, or `null` if not set.
</ResponseField>

<ResponseField name="status" type="string">
  `"pending"`.
</ResponseField>

<ResponseField name="queued" type="boolean">
  `true`.
</ResponseField>

<ResponseField name="warnings" type="object[]">
  Array of validation warnings indicating integrations that will be skipped due to missing data. Each warning contains:

  <Expandable title="warning properties">
    <ResponseField name="integration" type="string">The integration that will be skipped (e.g. `"google_ads"`, `"ga4"`, `"meta"`)</ResponseField>
    <ResponseField name="reason" type="string">Human-readable explanation of why the integration was skipped</ResponseField>
    <ResponseField name="field" type="string">The specific field that is missing (e.g. `"gclid"`, `"cid"`, `"user_data"`)</ResponseField>
    <ResponseField name="timestamp" type="string">ISO 8601 timestamp of when the warning was generated</ResponseField>
  </Expandable>
</ResponseField>

### Error: duplicate job (409)

If the lead already has a pending job in the processing queue, a `409 Conflict` is returned.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.leadtrackr.io/api/leads/updateLeadStatus \
    -H "Content-Type: application/json" \
    -H "X-API-Key: your-api-key-here" \
    -d '{
      "leadId": 42,
      "conversionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "price": 5000
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://app.leadtrackr.io/api/leads/updateLeadStatus", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "your-api-key-here"
    },
    body: JSON.stringify({
      leadId: 42,
      conversionId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      price: 5000
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  $ch = curl_init("https://app.leadtrackr.io/api/leads/updateLeadStatus");

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          "Content-Type: application/json",
          "X-API-Key: your-api-key-here"
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "leadId" => 42,
          "conversionId" => "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "price" => 5000
      ])
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "message": "Lead queued for processing",
    "leadId": 42,
    "uniqueIdentifier": "crm-lead-456",
    "status": "pending",
    "queued": true,
    "warnings": []
  }
  ```
</ResponseExample>