API Documentation

Authentication

All API requests require authentication using an API key. Include your API key in the request header for every call.

curl -X GET "https://api.safestreamleads.com/v2/leads" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

Obtaining API Credentials

API credentials are issued to approved partners only. To request access:

1. Complete the partner application form
2. Pass compliance verification
3. Sign the data processing agreement
4. Receive your API key via secure channel

Base URL

All API requests should be made to the following base URL:

https://api.safestreamleads.com/v2

For sandbox/testing environment:

https://sandbox.safestreamleads.com/v2

Rate Limits

To ensure platform stability, API requests are rate limited based on your partnership tier:

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699459200

Error Handling

The API uses standard HTTP response codes to indicate success or failure:

Error responses include a JSON body with details:

{
  "error": {
    "code": "INVALID_FIELD",
    "message": "The 'email' field is not a valid email address",
    "field": "email"
  }
}

Lead Endpoints

curl -X POST "https://api.safestreamleads.com/v2/leads" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@email.com",
    "phone": "5551234567",
    "state": "CA",
    "zip_code": "90210",
    "loan_amount": 5000,
    "loan_purpose": "debt_consolidation",
    "employment_status": "employed",
    "annual_income": 65000,
    "credit_rating": "good",
    "tcpa_consent": true,
    "consent_timestamp": "2026-02-21T10:30:00Z",
    "ip_address": "192.168.1.1",
    "source_url": "https://example.com/apply"
  }'

{
  "success": true,
  "lead_id": "ld_7x8k2m9n4p5q",
  "status": "accepted",
  "price": 45.00,
  "buyer_id": "by_abc123",
  "created_at": "2026-02-21T10:30:05Z"
}

{
  "lead_id": "ld_7x8k2m9n4p5q",
  "status": "sold",
  "disposition": "contacted",
  "buyer_id": "by_abc123",
  "price": 45.00,
  "created_at": "2026-02-21T10:30:05Z",
  "sold_at": "2026-02-21T10:30:07Z",
  "last_updated": "2026-02-21T14:22:00Z"
}

Webhooks

Configure webhooks to receive real-time notifications when lead statuses change. Webhooks are sent as HTTP POST requests to your configured endpoint.

Webhook Events

Webhook Payload

{
  "event": "lead.accepted",
  "lead_id": "ld_7x8k2m9n4p5q",
  "timestamp": "2026-02-21T10:30:07Z",
  "data": {
    "status": "sold",
    "price": 45.00,
    "buyer_id": "by_abc123"
  }
}

Field Reference

Loan Purpose Values

"debt_consolidation" | "home_improvement" | "major_purchase" |
"medical" | "auto" | "business" | "vacation" | "other"

Employment Status Values

"employed" | "self_employed" | "retired" |
"military" | "unemployed" | "student"

Credit Rating Values

"excellent" (720+) | "good" (680-719) |
"fair" (640-679) | "poor" (<640)