# SocioLogic Trace API - Full Documentation

> Skip tracing API - find contact info for property owners. Pay per call with USDC on Base via x402.

SocioLogic Trace provides instant skip trace lookups. Given a name and address, get phone numbers (with type and DNC status), email addresses, and optionally discover property owner information including name, age, and date of birth.

## Quick Start

All paid endpoints require x402 payment. Send a request, receive a 402 Payment Required response with payment details, complete the USDC payment on Base, then retry with the payment proof.

## Endpoints

### Free Endpoints (No Payment Required)

#### GET /
Returns API information, pricing, and endpoint documentation.

#### GET /health
Returns service status.
Response: `{"status": "ok", "timestamp": "2025-01-21T12:00:00.000Z"}`

#### GET /.well-known/x402
Returns x402 discovery document with resource list and ownership proof.

#### GET /.well-known/x402.json
Returns machine-readable x402 payment manifest with endpoint pricing.

---

### Trace Lookup - $0.12 per hit

#### POST /trace
Perform an instant skip trace lookup for a person at an address.

**Request Body:**
```json
{
  "first_name": "John",
  "last_name": "Doe",
  "address": "123 Main St",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "find_owner": true
}
```

**Fields:**
- `first_name` (string, required when find_owner is false): First name of the person to trace
- `last_name` (string, required when find_owner is false): Last name of the person to trace
- `address` (string, required): Street address
- `city` (string, required): City
- `state` (string, required): State (2-letter abbreviation)
- `zip` (string, optional): ZIP code
- `find_owner` (boolean, optional, default: true): When true, discovers property owner info - first_name and last_name are not required. Set to false to skip owner discovery; first_name and last_name become required.

**Response (find_owner=true, default):**
```json
{
  "persons": [
    {
      "phones": [
        { "number": "5125551234", "type": "Mobile", "dnc": false, "carrier": "CARRIER NAME", "rank": 1 }
      ],
      "emails": [
        { "email": "john.doe@example.com", "rank": 1 }
      ],
      "owner": {
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "age": "45",
        "dob": "1980-03-15",
        "deceased": false,
        "property_owner": true,
        "litigator": false
      },
      "mailing_address": {
        "street": "456 Oak Ave",
        "city": "Austin",
        "state": "TX",
        "zip": "78702"
      }
    }
  ],
  "charged": true
}
```

**Response (find_owner=false):**
```json
{
  "persons": [
    {
      "phones": [
        { "number": "5125551234", "type": "Mobile", "dnc": false, "carrier": "CARRIER NAME", "rank": 1 }
      ],
      "emails": [
        { "email": "john.doe@example.com", "rank": 1 }
      ],
      "owner": {
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "age": "45",
        "dob": "1980-03-15",
        "deceased": false,
        "property_owner": true,
        "litigator": false
      },
      "mailing_address": {
        "street": "456 Oak Ave",
        "city": "Austin",
        "state": "TX",
        "zip": "78702"
      }
    }
  ],
  "charged": true
}
```

**Miss (no results - not charged via x402; MPP payments are non-refundable):**
```json
{
  "persons": [],
  "miss": true,
  "charged": false
}
```

---

## Error Handling

All errors return JSON with this structure:
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

**Common Error Codes:**
- `INVALID_INPUT`: Missing or invalid fields
- `INVALID_JSON`: Malformed JSON request body
- `UPSTREAM_ERROR`: Trace service returned an error
- `SERVICE_UNAVAILABLE`: Service configuration issue
- `PAYMENT_ERROR`: Payment processing failed
- `PAYMENT_REQUIRED`: No valid payment provided
- `RATE_LIMITED`: Too many requests (free endpoints only)

---

## Payment Details

### x402 Protocol
This API uses the x402 payment protocol for micropayments.

**Network:** Base Mainnet (Chain ID: 8453)
**Currency:** USDC
**Facilitator:** Coinbase Developer Platform
**Payment Address:** 0x0b6E3594Df4Faa6D66196D5a3271796AD8Bb505d

### Payment Flow
1. Request a paid endpoint
2. Receive 402 Payment Required with payment instructions
3. Submit USDC payment on Base
4. Retry request with X-PAYMENT header containing payment proof
5. Receive response

---

## Deployment
- Platform: Cloudflare Workers
- Latency: <100ms globally (plus upstream API time)
- Upstream timeout: 15 seconds (requests may take up to 15 seconds)
- Availability: 99.9%+ uptime

---

## Rate Limits

**Free endpoints only (/, /health):**
- 60 requests per minute per IP
- No rate limits on paid endpoints

---

## Contact

- Website: https://www.sociologic.ai
- Email: team@sociologic.ai
- Documentation: https://www.sociologic.ai/docs