DataBridge Integration Guide - Lead Data API Documentation

API Integration

Getting Started

Our RESTful API accepts JSON payloads via HTTPS POST requests only. All requests require dual-token authentication via API key and provider token, and support batch processing for high-volume integrations.

Endpoint Information

POST

https://leads4.pro/databridge/api/ingest/

Authentication

Your API key and provider token are listed above and must be included in every request. Both the API key and 6-letter provider token must be included in the JSON request body. No special headers required.

HTTP Headers (POST only)

Content-Type: application/json

POST Method

Send lead data as JSON in the request body. This is the only supported method for lead submissions.

JSON Payload Structure - All Possible Fields

{
  "api_key": "your_api_key_here",
  "provider_token": "YOUR_6_LETTER_TOKEN",
  "test": true,
  "leads": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "5551234567",
      "address": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90210",
      "homeowner": "yes",
      "ip_address": "192.168.1.100",
      "vertical": "bathroom_remodel",
      "tcpa_language": "I agree to receive calls and texts regarding home improvement quotes",
      "trustedform_cert_url": "https://cert.trustedform.com/abc123def456",
      "jornaya_leadid": "jornaya_lead_id_here",
      "landing_page_url": "https://example.com/bathroom-remodel-form",
      "clickid": "click_12345",
      "sub1": "campaign_summer_2024",
      "sub2": "source_google_ads",
      "sub3": "medium_cpc",
      "sub4": "keyword_bathroom_remodel",
      "sub5": "ad_group_california",
      "credit_score": 720,
      "custom_field_1": "project_type_full_remodel",
      "custom_field_2": "budget_range_15000_25000",
      "custom_field_3": "timeline_3_6_months",
      "custom_field_4": "home_age_built_1995",
      "custom_field_5": "bathtoshower"
    }
  ]
}

cURL Example (POST)

POST Request with cURL

curl -X POST https://leads4.pro/databridge/api/ingest/ \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    "provider_token": "YOUR_6_LETTER_TOKEN",
    "test": true,
    "leads": [{
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "5551234567",
      "zip": "90210",
      "homeowner": "yes",
      "ip_address": "192.168.1.100",
      "vertical": "bathroom_remodel",
      "tcpa_language": "I agree to receive calls and texts regarding home improvement quotes",
      "landing_page_url": "https://example.com/bathroom-remodel-form",
      "trustedform_cert_url": "https://cert.trustedform.com/abc123"
    }]
  }'

Field Documentation

Field Name	Type	Required	Description	Example
`api_key`	String	Required	Your unique API authentication key	your_api_key_here
`provider_token`	String	Required	Your 6-letter provider identification token	ABCDEF
`vertical`	String	Required	Lead vertical/category	bathroom_remodel
`first_name`	String	Required	Lead's first name	John
`last_name`	String	Required	Lead's last name	Doe
`email`	String	Required	Valid email address	john.doe@example.com
`phone`	String	Required	10-digit US phone number	5551234567
`address`	String	Optional	Street address	123 Main St
`city`	String	Optional	City name	Los Angeles
`state`	String	Optional	2-letter state code	CA
`zip`	String	Required	5-digit ZIP code	90210
`homeowner`	String	Optional	Whether the lead is a homeowner (values: "yes" or "no")	yes
`ip_address`	String	Required	Lead's IP address (IPv4 or IPv6)	192.168.1.100
`tcpa_language`	String	Required	TCPA consent language shown to lead	I agree to receive calls and texts regarding home improvement quotes
`trustedform_cert_url`	String	Required*	TrustedForm certificate URL (*Either this OR jornaya_leadid required)	https://cert.trustedform.com/abc123def456
`jornaya_leadid`	String	Required*	Jornaya LeadiD for lead verification (*Either this OR trustedform_cert_url required)	jornaya_lead_id_here
`landing_page_url`	String	Required	URL where lead was captured	https://example.com/bathroom-remodel-form
`clickid`	String	Optional	Click tracking identifier	click_12345
`sub1`	String	Optional	Custom tracking parameter 1	campaign_summer_2024
`sub2`	String	Optional	Custom tracking parameter 2	source_google_ads
`sub3`	String	Optional	Custom tracking parameter 3	medium_cpc
`sub4`	String	Optional	Custom tracking parameter 4	keyword_bathroom_remodel
`sub5`	String	Optional	Custom tracking parameter 5	ad_group_california
`credit_score`	Integer	Optional	Lead's credit score (300-850)	720
`custom_field_1`	String	Optional	Custom data field 1	project_type_full_remodel
`custom_field_2`	String	Optional	Custom data field 2	budget_range_15000_25000
`custom_field_3`	String	Optional	Custom data field 3	timeline_3_6_months
`custom_field_4`	String	Optional	Custom data field 4	home_age_built_1995
`custom_field_5`	String	Optional	Custom data field 5 (e.g., bathtoshower, homeowner_yes, etc.)	bathtoshower

Compliance Requirements

TCPA language is required for all leads. Additionally, either a TrustedForm certificate URL OR Jornaya LeadiD must be provided for compliance verification. Including both is recommended for maximum lead quality and buyer acceptance rates.

Supported Verticals

Home Improvement Verticals

bathroom_remodel - Bathroom Remodel
walkin_tubs - Walk-in Tubs
hvac - HVAC Systems
window_replacement - Window Replacement
flooring - Flooring Installation

Additional Verticals

kitchen_remodel - Kitchen Remodel
roofing - Roofing Services
solar - Solar Installation
exterior_painting - Exterior Painting
custom - Custom Verticals

Response Format

Success Response

HTTP 200 - Lead Accepted

{
 "lead_id": "A7K9M2X5P8Q1",
 "status": "accepted",
 "test_mode": false
}

Error Response

HTTP 400 - Validation Error

{
 "lead_id": null,
 "status": "rejected",
 "reason": "validation_error",
 "error": "Missing required field: email"
}

Testing & Validation

Test Environment

Use the same endpoint for testing with your production API key. Test leads are automatically flagged and won't be distributed to live buyers. Include "test": true in your payload for explicit test mode.

Test Lead Examples

POST Method Test

Test Mode Payload (POST)

{
  "api_key": "your_api_key_here",
  "provider_token": "YOUR_6_LETTER_TOKEN",
  "test": true,
  "leads": [{
    "first_name": "Test",
    "last_name": "User",
    "email": "test@example.com",
    "phone": "5555555555",
    "zip": "90210",
    "homeowner": "yes",
    "ip_address": "192.168.1.100",
    "vertical": "bathroom_remodel",
    "tcpa_language": "I agree to receive calls and texts regarding home improvement quotes",
    "trustedform_cert_url": "https://cert.trustedform.com/test123",
    "landing_page_url": "https://example.com/bathroom-remodel-test-form"
  }]
}

Validation Checklist

Valid email format
10-digit US phone number
5-digit ZIP code
Supported vertical
Valid landing page URL

Required TCPA compliance language
TrustedForm OR Jornaya compliance
Credit score (if available)
Unique provider lead ID