Lead Posting API - Pingtree Documentation

POST

api

lead

create

{db-source-id}

cURL

curl --request POST \
  --url https://api.pingtree.com/api/lead/create/{db-source-id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "mobile": "<string>",
  "address": "<string>",
  "state": "<string>",
  "city": "<string>",
  "zip_code": "<string>",
  "date_of_birth": "<string>"
}
'

{
  "status": "<string>",
  "message": "<string>",
  "data": {}
}

Overview

The Database Source Lead Posting API creates a new lead record directly in a database source. Unlike the offer campaign form API, this endpoint stores leads in a standalone database source — used as a centralised lead repository, suppression list, or feed for downstream campaigns. Both GET and POST HTTP methods are supported. Authentication is via the database source’s API key, which is auto-generated when the source is created.

Endpoint

POST /api/lead/create/{db-source-id}
GET  /api/lead/create/{db-source-id}

Replace {db-source-id} with the MongoDB Object ID of the database source. This is available in the Pingtree dashboard under Database Sources.

Authentication

Include the database source API key in the Authorization header:

Authorization: Bearer <db-source-api-key>

The API key is generated when the database source is created and can be found on the source’s detail page.

Request Parameters

Path Parameters

Parameter	Type	Required	Description
`db-source-id`	string	Yes	MongoDB Object ID of the database source

Body / Query Parameters

Fields accepted depend on the required fields configured for the database source. Common system fields include:

Parameter	Type	Required	Description
`first_name`	string	Conditional	Consumer’s first name
`last_name`	string	Conditional	Consumer’s last name
`email`	string	Conditional	Email address (validated as a valid email format)
`mobile`	string	Conditional	10-digit phone number (digits only)
`address`	string	Conditional	Street address
`city`	string	Conditional	City name (letters and spaces only)
`state`	string	Conditional	2-letter state abbreviation
`zip_code`	string	Conditional	5-digit ZIP code
`transaction_id`	string	No	Custom transaction ID; auto-generated if omitted

For GET requests, pass parameters as query string values. For POST requests, send as a JSON body or form-encoded body. The exact required fields are configured per database source. Invalid or missing required fields result in rejection with a list of affected field names.

Example Request — POST

curl -X POST "https://api.pingtree.com/api/lead/create/64a1b2c3d4e5f6a7b8c9d0e1" \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Connor",
    "email": "sarah.connor@example.com",
    "mobile": "3105559876",
    "address": "999 Future Rd",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "90210"
  }'

Example Request — GET

curl "https://api.pingtree.com/api/lead/create/64a1b2c3d4e5f6a7b8c9d0e1?first_name=Sarah&last_name=Connor&email=sarah.connor%40example.com&mobile=3105559876&zip_code=90210" \
  -H "Authorization: Bearer sk_live_abc123xyz789..."

Example Responses

Success — Lead Created

{
  "status": 201,
  "message": "Lead successfully created",
  "data": {
    "leadStatus": "accept",
    "transaction_id": "db_txn_7f3a2b1c-4d56-78ef-9012-abcdef123456"
  }
}

Success — Duplicate Lead

{
  "status": 201,
  "message": "Duplicate lead",
  "data": {
    "leadStatus": "duplicate",
    "transaction_id": "db_txn_7f3a2b1c-4d56-78ef-9012-abcdef123456"
  }
}

Error — Missing Required Field

{
  "status": 400,
  "message": "Missing required fields",
  "data": {
    "leadStatus": "missingField",
    "missingFields": ["email", "mobile"]
  }
}

Error — Invalid Field

{
  "status": 400,
  "message": "Invalid field value",
  "data": {
    "leadStatus": "invalidField",
    "invalidFields": ["email"]
  }
}

Error — Unauthorized

{
  "status": 401,
  "message": "Unauthorized"
}

Error — Source Not Found or Inactive

{
  "status": 400,
  "message": "Database source not found or inactive"
}

Status Codes

HTTP Code	Lead Status	Description
201	`accept`	Lead created successfully
201	`duplicate`	Lead already exists (deduplication enabled and matched)
400	`missingField`	One or more required fields are absent
400	`invalidField`	One or more fields failed format validation
401	—	Invalid or missing API key
500	—	Internal server error

Deduplication

If the database source has deduplication enabled, the configured duplicate field (e.g. email or mobile) is checked against existing records before the lead is stored. If a match is found, the lead status is duplicate and the record is not stored again.

Tips

API key security. The database source API key grants write access to that source. Keep it confidential and rotate it if compromised (via the Pingtree dashboard).
GET vs POST. GET requests are useful for simple server-to-server integrations or pixel-style firing. POST with a JSON body is recommended for production use.
Allowed fields list. The source can be configured with an allowed fields list that restricts which fields are accepted. Fields outside this list are silently ignored.
TrustedForm fields. xxTrustedFormToken, xxTrustedFormCertUrl, and xxTrustedFormPingUrl are automatically mapped to internal fields if present in the request.
Rate limiting. Database source endpoints are rate-limited per source. Contact your account manager if you need higher throughput limits.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

db-source-id

string

required

Your database source ID

Body

application/json

Lead details to add to the database source

first_name

string

First name of the lead

last_name

string

Last name of the lead

string

Email of the lead

mobile

string

Mobile of the lead

address

string

Address of the lead

state

string

State of the lead

city

string

City of the lead

zip_code

string

Zip Code of the lead

date_of_birth

string

Date of Birth of the lead

Response

Lead successfully created

status

string

Status code of API response

message

string

Message of API response

data

object

Created lead information such as transaction_id, lead_status, etc.

Lead Fetch APIThe Fetch Lead API allows users to retrieve stored lead data from the database source. This functionality is useful for validating data, generating reports, or ensuring seamless follow-ups.

cURL

curl --request POST \
  --url https://api.pingtree.com/api/lead/create/{db-source-id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "mobile": "<string>",
  "address": "<string>",
  "state": "<string>",
  "city": "<string>",
  "zip_code": "<string>",
  "date_of_birth": "<string>"
}
'

{
  "status": "<string>",
  "message": "<string>",
  "data": {}
}

Documentation Index

​Overview

​Endpoint

​Authentication

​Request Parameters

​Path Parameters

​Body / Query Parameters

​Example Request — POST

​Example Request — GET

​Example Responses

​Success — Lead Created

​Success — Duplicate Lead

​Error — Missing Required Field

​Error — Invalid Field

​Error — Unauthorized

​Error — Source Not Found or Inactive

​Status Codes

​Deduplication

​Tips

Authorizations

Path Parameters

Body

Response

Overview

Endpoint

Authentication

Request Parameters

Path Parameters

Body / Query Parameters

Example Request — POST

Example Request — GET

Example Responses

Success — Lead Created

Success — Duplicate Lead

Error — Missing Required Field

Error — Invalid Field

Error — Unauthorized

Error — Source Not Found or Inactive

Status Codes

Deduplication

Tips