> ## 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. # Create Source Form API > The API URL serves as the endpoint where the traffic source submits lead data. This URL must be installed and used by the source sending the data to ensure it’s received properly by Pingtree. [Find detailed documentation here](/documentation/campaign/source-single-view/Form-API-(CS,-MC,-MP)). Use [Generate Specs](/documentation/campaign/source-single-view/Generate-Specs-(CS,-MC,-MP)) feature to get the api specification for this endpoint. ## Overview The Source Form API is the primary lead submission endpoint for a specific campaign source. It accepts a full lead record from a publisher or media partner and routes it through the campaign's distribution logic. This endpoint is equivalent to the Create Form API but is scoped to a source identified by its unique link ID rather than a campaign ID. It is the endpoint listed in your posting specification under "Form API". ## Endpoint ``` POST /api/lead/add/{source-unique-id} ``` Replace `{source-unique-id}` with the `linkUniqueId` provided in your posting specification. This value is unique per source-campaign pairing. ## Authentication Include the source API token in the `Authorization` header: ``` Authorization: Bearer ``` The token is listed in your posting specification under the Form API section. ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | | ------------------ | ------ | -------- | ----------------------------------------------- | | `source-unique-id` | string | Yes | Link unique ID for this source-campaign pairing | ### Body Parameters (JSON or form-encoded) | Parameter | Type | Required | Description | | ---------------------- | ------ | ----------- | ------------------------------------------------------------- | | `first_name` | string | Conditional | Consumer's first name | | `last_name` | string | Conditional | Consumer's last name | | `email` | string | Conditional | Valid email address | | `mobile` | string | Conditional | 10-digit phone number (digits only) | | `address` | string | Conditional | Street address | | `city` | string | Conditional | City name | | `state` | string | Conditional | 2-letter state code (e.g. `TX`) | | `zip_code` | string | Conditional | 5-digit ZIP code | | `country` | string | No | Country code (default: `US`) | | `date_of_birth` | string | No | YYYY-MM-DD format | | `transaction_id` | string | No | Publisher-generated transaction ID; auto-generated if omitted | | `sub1` – `sub5` | string | No | Publisher sub-tracking parameters | | `adv1` – `adv5` | string | No | Advertiser sub-parameters | | `utm_source` | string | No | UTM source value | | `utm_medium` | string | No | UTM medium value | | `utm_campaign` | string | No | UTM campaign value | | `utm_term` | string | No | UTM term value | | `utm_content` | string | No | UTM content value | | `gclid` | string | No | Google Click ID | | `fbclid` | string | No | Facebook Click ID | | `ttclid` | string | No | TikTok Click ID | | `jornaya` | string | No | Jornaya LeadiD token | | `xxTrustedFormCertUrl` | string | No | TrustedForm certificate URL | | `tcpa_consent` | string | No | TCPA consent value | | `tcpa_consent_date` | string | No | TCPA consent timestamp | Campaign-specific custom fields (e.g. `loan_amount`, `home_owner`, `insurance_type`) may also be required. Your posting specification lists all active fields with their required status. ## Example Request ```bash theme={null} curl -X POST "https://api.pingtree.com/api/lead/add/lnk_abc123xyz" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "first_name": "John", "last_name": "Smith", "email": "john.smith@example.com", "mobile": "4085559876", "address": "456 Oak Avenue", "city": "Austin", "state": "TX", "zip_code": "73301", "loan_amount": 20000, "credit_score": "fair", "sub1": "pub-campaign-001", "transaction_id": "pub_txn_998877" }' ``` ## Example Responses ### Success — Lead Accepted (Sold) ```json theme={null} { "status": "201", "message": "Lead successfully created", "transaction_id": "pub_txn_998877", "data": { "transaction_id": "pub_txn_998877", "leadStatus": "accepted", "redirect_url": "https://offer.example.com/debt?tid=pub_txn_998877" }, "isDeDupe": false } ``` ### Success — Lead Unsold ```json theme={null} { "status": "201", "message": "Lead accepted", "transaction_id": "pub_txn_998877", "data": { "transaction_id": "pub_txn_998877", "leadStatus": "unsold", "redirect_url": "https://fallback.example.com" }, "isDeDupe": false } ``` ### Error — Invalid Field ```json theme={null} { "status": "400", "message": "Invalid field: mobile", "transaction_id": "pub_txn_998877", "data": { "leadStatus": "invalidField" }, "isDeDupe": false } ``` ## Status Codes | HTTP Code | Lead Status | Description | | --------- | -------------- | ----------------------------------------------------------- | | 201 | `accepted` | Lead distributed to at least one buyer | | 201 | `unsold` | Lead recorded but not distributed (cap, filters, no buyers) | | 400 | `missingField` | Required field absent from the request | | 400 | `invalidField` | Field value did not pass format validation | | 400 | `rejected` | Lead rejected by campaign rules | | 401 | `rejected` | Invalid or missing API token | | 405 | `rejected` | HTTP method not allowed | | 500 | `rejected` | Internal server error | ## Tips * **Check your posting spec:** The exact list of required and optional fields, acceptable values, and field descriptions are auto-generated in your campaign's posting specification page. * **Mobile number format:** Send only digits. The API strips non-digit characters, but a 10-digit number is required (e.g. `4085559876` not `+1 (408) 555-9876`). * **Custom transaction IDs:** If you supply a `transaction_id`, it must be unique per lead. Reusing an ID may overwrite or conflict with existing records. * **Redirect handling:** Store the `redirect_url` from the response and immediately redirect the consumer to it for optimal conversion. * **ZIP code lookup:** The API can resolve `city` and `state` from `zip_code` if those fields are not submitted, depending on campaign configuration. ## OpenAPI ````yaml POST /api/lead/add/{source-unique-id} 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/add/{source-unique-id}: post: description: >- The API URL serves as the endpoint where the traffic source submits lead data. This URL must be installed and used by the source sending the data to ensure it’s received properly by Pingtree. [Find detailed documentation here](/documentation/campaign/source-single-view/Form-API-(CS,-MC,-MP)). Use [Generate Specs](/documentation/campaign/source-single-view/Generate-Specs-(CS,-MC,-MP)) feature to get the api specification for this endpoint. ````