> ## 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 Form API > The Create Form API is designed to enable seamless lead form creation and submission. It is ideal for capturing user data directly from landing pages or campaign websites, ensuring that lead information is collected accurately and efficiently. ## Overview The Create Form API submits a lead captured from a landing page or campaign form directly into the Pingtree lead distribution system. The lead is evaluated, distributed to buyers, and a response is returned indicating acceptance status, redirect URL, and deduplication state. ## Endpoint ``` POST /api/lead/add/{source-unique-id} ``` Replace `{source-unique-id}` with the unique link ID assigned to your campaign source (found in your posting spec). ## Authentication Include your API token in the `Authorization` header: ``` Authorization: Bearer ``` The token is source-specific and is provided in your campaign's posting specification. ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------------------------- | | `source-unique-id` | string | Yes | The unique link identifier for the campaign source | ### 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 | Consumer's email address | | `mobile` | string | Conditional | 10-digit mobile number (digits only) | | `address` | string | Conditional | Street address | | `city` | string | Conditional | City name | | `state` | string | Conditional | State abbreviation (e.g. `CA`) | | `zip_code` | string | Conditional | 5-digit ZIP code | | `country` | string | No | Country code (default: `US`) | | `date_of_birth` | string | No | Date of birth (YYYY-MM-DD) | | `transaction_id` | string | No | Pre-generated transaction ID; one is created if omitted | | `sub1` – `sub5` | string | No | Publisher sub-parameters for tracking | | `adv1` – `adv5` | string | No | Advertiser sub-parameters | | `utm_source` | string | No | UTM source | | `utm_medium` | string | No | UTM medium | | `utm_campaign` | string | No | UTM campaign | | `utm_term` | string | No | UTM term | | `utm_content` | string | No | UTM content | | `gclid` | string | No | Google Click ID | | `fbclid` | string | No | Facebook Click ID | | `ttclid` | string | No | TikTok Click ID | | `jornaya` | string | No | Jornaya lead ID token | | `xxTrustedFormCertUrl` | string | No | TrustedForm certificate URL | | `tcpa_consent` | string | No | TCPA consent flag | | `tcpa_consent_date` | string | No | TCPA consent timestamp | Required fields depend on the campaign configuration. Check your posting spec for the exact list of required fields. ## 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": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "mobile": "5551234567", "address": "123 Main St", "city": "Los Angeles", "state": "CA", "zip_code": "90001", "sub1": "campaign-abc", "utm_source": "google", "utm_medium": "cpc" }' ``` ## Example Responses ### Success — Lead Accepted ```json theme={null} { "status": "201", "message": "Lead successfully created", "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 } ``` ### Success — Duplicate Lead ```json theme={null} { "status": "201", "message": "Lead accepted as duplicate", "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456", "data": { "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456", "leadStatus": "unsold", "redirect_url": "https://thank-you.example.com" }, "isDeDupe": true } ``` ### Error — Missing Required Field ```json theme={null} { "status": "400", "message": "Missing required field: email", "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456", "data": { "leadStatus": "missingField" }, "isDeDupe": false } ``` ### Error — Unauthorized ```json theme={null} { "status": "401", "message": "Unauthorized", "data": { "leadStatus": "rejected" } } ``` ## Status Codes | HTTP Code | Lead Status | Description | | --------- | -------------- | ------------------------------------------------------------------- | | 201 | `accepted` | Lead was accepted and distributed | | 201 | `unsold` | Lead was recorded but not distributed (e.g. duplicate, cap reached) | | 400 | `missingField` | One or more required fields are absent | | 400 | `invalidField` | One or more fields failed format validation | | 400 | `rejected` | Lead was rejected by the campaign rules | | 401 | `rejected` | Invalid or missing authorization token | | 405 | `rejected` | HTTP method not allowed | | 500 | `rejected` | Internal server error | ## Tips * **Mobile format:** Strip all non-digit characters before submitting. The API normalises the field automatically, but sending `555-123-4567` or `(555) 123-4567` both work. * **Deduplication:** If deduplication is enabled for the campaign, the `isDeDupe` flag in the response indicates whether this lead was seen before. * **Redirect URL:** Use `redirect_url` from the response to forward the consumer to a thank-you page or offer wall. * **Custom fields:** Additional campaign-specific fields (e.g. `loan_amount`, `home_owner`) may be required. Check your posting spec for the complete field list. * **Rate limits:** Each campaign source has a configurable rate limit. Exceeding it returns a `429 Too Many Requests` response. ## OpenAPI ````yaml POST /api/lead/{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/{cid}: post: description: >- The Create Form API is designed to enable seamless lead form creation and submission. It is ideal for capturing user data directly from landing pages or campaign websites, ensuring that lead information is collected accurately and efficiently. 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: 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 isDeDupe: type: string description: >- Flag for dedup which confirms that lead is duplicate or not lead_status: type: string description: Current status of lead which can be sold or unsold or new redirect_url: type: string description: Response Redirect URL of API response buyer_type: type: string description: Buyer response type for lead sold buyer_name: type: string description: Current buyer name for lead sold buyer_response: type: string description: Entire buyer response which we get from buyer's endpoint '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 ````