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

# Update Lead API

> The Update Form API is used to modify existing lead form data within a campaign. This API is especially useful when updating incorrect details, adding new information, or making adjustments to previously submitted leads to ensure accurate campaign records.

## Overview

The Update Lead API enriches or corrects an existing lead record in a campaign. Use it when additional data becomes available after initial submission — for example, after a secondary form step, a phone verification flow, or a credit check callback. The lead is identified by `transaction_id` and the campaign's offer campaign ID.

## Endpoint

```
POST /api/lead/update/{offerCampaignId}
```

Replace `{offerCampaignId}` with the unique identifier of the offer campaign (available in your posting spec or dashboard).

## Authentication

Include the enrichment token in the `Authorization` header:

```
Authorization: Bearer <your-enrichment-token>
```

The enrichment token is distinct from the standard form API token and is listed separately in your posting specification.

## Request Parameters

### Path Parameters

| Parameter         | Type   | Required | Description                         |
| ----------------- | ------ | -------- | ----------------------------------- |
| `offerCampaignId` | string | Yes      | The unique ID of the offer campaign |

### Body Parameters (JSON)

| Parameter        | Type   | Required | Description                                                 |
| ---------------- | ------ | -------- | ----------------------------------------------------------- |
| `transaction_id` | string | Yes      | The transaction ID returned by the original lead submission |
| `first_name`     | string | No       | Updated first name                                          |
| `last_name`      | string | No       | Updated last name                                           |
| `email`          | string | No       | Updated email address                                       |
| `mobile`         | string | No       | Updated 10-digit mobile number                              |
| `address`        | string | No       | Updated street address                                      |
| `city`           | string | No       | Updated city                                                |
| `state`          | string | No       | Updated state abbreviation                                  |
| `zip_code`       | string | No       | Updated ZIP code                                            |
| `date_of_birth`  | string | No       | Updated date of birth (YYYY-MM-DD)                          |
| `sub1` – `sub5`  | string | No       | Updated publisher sub-parameters                            |
| `adv1` – `adv5`  | string | No       | Updated advertiser sub-parameters                           |

Any campaign-specific custom fields (e.g. `loan_amount`, `credit_score`) can also be included in the body. Only fields present in the request body are updated; existing field values are not overwritten if omitted.

## Example Request

```bash theme={null}
curl -X POST "https://api.pingtree.com/api/lead/update/cmp_9z8y7x6w" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "loan_amount": 15000,
    "credit_score": "good",
    "home_owner": true
  }'
```

## Example Responses

### Success — Lead Updated

```json theme={null}
{
  "status": "201",
  "message": "Lead successfully updated",
  "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
  "data": {
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "leadStatus": "accepted",
    "redirect_url": "https://thank-you.example.com?tid=txn_7f3a2b1c"
  },
  "isDeDupe": false
}
```

### Error — Missing Transaction ID

```json theme={null}
{
  "status": "400",
  "message": "transaction_id is required",
  "data": {
    "leadStatus": "missingField"
  }
}
```

### Error — Lead Not Found

```json theme={null}
{
  "status": "400",
  "message": "Lead not found for the given transaction_id",
  "data": {
    "leadStatus": "rejected"
  }
}
```

### Error — Unauthorized

```json theme={null}
{
  "status": "401",
  "message": "Unauthorized",
  "data": {
    "leadStatus": "rejected"
  }
}
```

## Status Codes

| HTTP Code | Lead Status    | Description                                                      |
| --------- | -------------- | ---------------------------------------------------------------- |
| 201       | `accepted`     | Lead was updated and re-evaluated successfully                   |
| 201       | `unsold`       | Lead was updated but not re-distributed                          |
| 400       | `missingField` | `transaction_id` or another required enrichment field is missing |
| 400       | `invalidField` | A field failed format validation                                 |
| 400       | `rejected`     | The lead record was not found or the update was rejected         |
| 401       | `rejected`     | Invalid or missing enrichment token                              |
| 405       | `rejected`     | HTTP method not allowed                                          |
| 500       | `rejected`     | Internal server error                                            |

## Tips

* **`transaction_id` is mandatory.** The update endpoint uses it to locate the original lead record. Always store this value from the initial form submission response.
* **Partial updates are safe.** Only send the fields you want to change. Fields not included in the request are left unchanged.
* **Re-distribution:** Depending on campaign settings, updating a lead may trigger re-distribution to buyers. Check with your campaign manager if re-posting behaviour is required.
* **Enrichment token vs form token:** These are different credentials. Using the wrong token returns a 401 error.


## OpenAPI

````yaml POST /api/lead/update/{cid}
openapi: 3.1.0
info:
  title: Pingtree API Explore
  description: >-
    The Pingtree API Explore is a comprehensive guide designed to help you
    understand and integrate the Pingtree API effectively. It provides detailed
    insights into API endpoints, request parameters, and response structures to
    facilitate seamless lead distribution and tracking. Whether you're building
    custom integrations, automating lead flows, or optimizing campaign
    performance, this guide empowers you with the knowledge to leverage
    Pingtree's capabilities for enhanced lead management and improved results.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.pingtree.com
security: []
paths:
  /api/lead/update/{cid}:
    post:
      description: >-
        The Update Form API is used to modify existing lead form data within a
        campaign. This API is especially useful when updating incorrect details,
        adding new information, or making adjustments to previously submitted
        leads to ensure accurate campaign records.
      parameters:
        - name: cid
          required: true
          in: path
          description: Your campaign unique ID
          schema:
            type: string
      requestBody:
        description: Lead details to add to the campaign
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lead'
      responses:
        '201':
          description: Lead successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead-response'
        '400':
          description: >-
            Unexpected error, transaction_id or cid not found in the requested
            data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead-response'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead-response'
components:
  schemas:
    lead:
      required:
        - transaction_id
      type: object
      properties:
        transaction_id:
          description: >-
            Lead's Transaction ID, Which was generate from click script of
            Pingtree
          type: string
        first_name:
          description: First name of the lead
          type: string
        last_name:
          description: Last name of the lead
          type: string
        email:
          description: Email of the lead
          type: string
        mobile:
          description: Mobile of the lead
          type: string
        address:
          description: Address of the lead
          type: string
        state:
          description: State of the lead
          type: string
        city:
          description: City of the lead
          type: string
        zip_code:
          description: Zip Code of the lead
          type: string
        date_of_birth:
          description: Date of Birth of the lead
          type: string
    lead-response:
      type: object
      properties:
        status:
          type: string
          description: Status code of API response
        type:
          type: string
          description: Type of API response which can be success or error
        message:
          type: string
          description: Message of API response

````