Database Source

Lead Posting API

POSThttps://api.pingtree.com/api/lead/create/{db-source-id}

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#

Bash

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#

Bash

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#

JSON

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

Success — Duplicate Lead#

JSON

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

Error — Missing Required Field#

JSON

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

Error — Invalid Field#

JSON

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

Error — Unauthorized#

JSON

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

Error — Source Not Found or Inactive#

JSON

{
  "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.