API Documentation

Integrate with the Titan Lead Group platform. Submit leads, manage campaigns, track transactions, and automate your lead workflow.

Session-Based Auth

Real-Time Routing

RESTful JSON API

Authentication

All API endpoints require an authenticated session. Log in via POST /api/auth/login with your credentials to establish a session cookie.

POST /api/auth/login
Content-Type: application/json

{
  "username": "your_username",
  "password": "your_password"
}

// Response
{
  "user": {
    "id": "uuid",
    "username": "your_username",
    "role": "buyer",
    "fullName": "Your Name",
    "email": "you@company.com"
  }
}

→ Lead Submission (Seller API)

POST/api/leads/ping

Send a ping with partial lead data to get a bid price before committing the full lead.

Request Body

{
  "vertical": "home_services",
  "subVertical": "plumbing",
  "consumerState": "CA",
  "consumerZip": "90210",
  "leadData": {
    "homeowner": true,
    "project_type": "repair"
  }
}

Response

{
  "pingId": "550e8400-e29b-41d4-a716-446655440000",
  "bidPrice": 45.00,
  "exclusiveBidPrice": 67.50,
  "expiresInSeconds": 120,
  "matchCount": 3
}

POST/api/leads/ingest

Submit a full lead for validation, matching, and routing. The lead goes through the entire pipeline: validate, match buyer campaigns, route to highest-scoring buyer, and settle.

Request Body

{
  "vertical": "home_services",
  "subVertical": "plumbing",
  "sourceType": "arb_purchase",
  "consumerName": "John Smith",
  "consumerEmail": "john@example.com",
  "consumerPhone": "3105551234",
  "consumerState": "CA",
  "consumerZip": "90210",
  "consumerCity": "Beverly Hills",
  "cost": "28.00",
  "leadData": {
    "project_type": "repair",
    "homeowner": true,
    "description": "Leaking kitchen faucet"
  },
  "consent": {
    "text": "By submitting this form, I agree...",
    "timestamp": "2026-03-03T10:30:00Z",
    "ip": "73.162.xxx.xxx"
  }
}

Response

{
  "success": true,
  "leadId": 1234,
  "status": "sold",
  "revenue": 55.00,
  "cost": 28.00,
  "margin": 27.00,
  "buyerId": 5,
  "matchCount": 3
}

→ Lead Management (Buyer API)

GET/api/leads?buyerId={id}

Retrieve all leads purchased by a specific buyer. Supports filtering by status, vertical, and date range.

Response

[
  {
    "id": 1234,
    "vertical": "home_services",
    "status": "sold",
    "consumerName": "John Smith",
    "consumerState": "CA",
    "consumerZip": "90210",
    "revenue": "55.00",
    "qualityScore": 85,
    "createdAt": "2026-03-03T10:30:15Z"
  }
]

POST/api/leads/{id}/return

Return a purchased lead within the allowed return window. A credit will be issued to the buyer's account.

Request Body

{
  "reason": "disconnected_phone"
}

Response

{
  "message": "Lead returned successfully"
}

→ Campaign Management

GET/api/buyer-campaigns?buyerId={id}

List all campaigns for a buyer. Campaigns define targeting (vertical, geo, filters), pricing, caps, and delivery settings.

Response

[
  {
    "id": 1,
    "buyerId": 5,
    "name": "CA Auto Insurance - Exclusive",
    "vertical": "auto_insurance",
    "geoTargets": { "states": ["CA", "NV", "AZ"] },
    "pricePerLead": "72.00",
    "dailyCap": 50,
    "status": "active",
    "priority": 3
  }
]

POST/api/buyer-campaigns

Create a new buyer campaign with targeting, pricing, and delivery configuration.

Request Body

{
  "buyerId": 5,
  "name": "New Campaign",
  "vertical": "home_services",
  "geoTargets": { "states": ["CA", "TX"] },
  "pricePerLead": "55.00",
  "bidType": "fixed",
  "dailyCap": 40,
  "deliveryMethod": "webhook",
  "pingPostEnabled": true,
  "exclusive": false,
  "returnWindowHours": 48,
  "priority": 2
}

Response

{
  "id": 10,
  "buyerId": 5,
  "name": "New Campaign",
  "status": "active"
}

→ Transactions & Billing

GET/api/transactions?buyerId={id}

List all financial transactions for a buyer or seller. Includes lead sales, purchases, return credits, and adjustments.

Response

[
  {
    "id": 100,
    "type": "lead_sale",
    "leadId": 1234,
    "buyerId": 5,
    "amount": "55.00",
    "status": "completed",
    "createdAt": "2026-03-03T10:30:15Z"
  }
]

→ Rejection Reason Codes

Code	Description
`invalid_phone_format`	Phone number is not a valid 10 or 11 digit number
`fake_phone_number`	Phone number is a known test/fake number
`invalid_email_format`	Email address does not pass format validation
`disposable_email`	Email uses a known disposable/temporary email provider
`duplicate_lead`	Lead matches an existing record within the dedupe window
`missing_field_*`	A required field for the vertical schema is missing