Skip to main content
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

ParameterTypeRequiredDescription
db-source-idstringYesMongoDB 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:
ParameterTypeRequiredDescription
first_namestringConditionalConsumer’s first name
last_namestringConditionalConsumer’s last name
emailstringConditionalEmail address (validated as a valid email format)
mobilestringConditional10-digit phone number (digits only)
addressstringConditionalStreet address
citystringConditionalCity name (letters and spaces only)
statestringConditional2-letter state abbreviation
zip_codestringConditional5-digit ZIP code
transaction_idstringNoCustom 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 CodeLead StatusDescription
201acceptLead created successfully
201duplicateLead already exists (deduplication enabled and matched)
400missingFieldOne or more required fields are absent
400invalidFieldOne 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

​
email
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.