API Documentation

Base URL

https://172-86-89-201.nip.io

Authentication

All requests require an API key. Include it in the request body:

{
    "api_key": "your-api-key-here"
}

Flexible Input NEW

The API now accepts free-form text via the "text" field. Our parser automatically recognizes names, addresses, phones, DOB, SSN from almost any format.

You can send either structured "data" or raw "text".

Supported input formats:

Multi-line (each field on its own line)
Pipe-separated: John Smith | 123 Main St | Dallas, TX 75201
Semicolon-separated: John Smith; 123 Main St; Dallas; TX; 75201
Comma-separated: John, Smith, 123 Main St, Dallas, TX, 75201
Mixed/messy formats (LinkedIn profiles, etc.)

Supported DOB formats:

MM/DD/YYYY — 03/30/1983
MM-DD-YYYY — 03-30-1983
YYYY-MM-DD — 1983-03-30
YYYY.MM.DD — 1983.03.30
DD.MM.YYYY — 30.03.1983
Month DD, YYYY — March 30, 1983

Example with text:

curl -X POST https://172-86-89-201.nip.io/api/v1/lookup \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_KEY",
    "service": "ssn_dob",
    "text": "John Smith\n123 Main St\nDallas\nTX\n75201"
  }'

Endpoints

POST /api/v1/lookup

Perform a lookup for any supported service.

Option 1 — Structured data:

{
    "api_key": "your-key",
    "service": "service_name",
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        ...
    }
}

Option 2 — Free-form text NEW:

{
    "api_key": "your-key",
    "service": "service_name",
    "text": "John Doe\n123 Main St\nDallas, TX 75201\n03/30/1983"
}

GET /api/v1/balance

Check your current balance.

GET /api/v1/balance?api_key=your-api-key-here

Response:

{
    "status": "success",
    "balance": 75.00,
    "client_name": "Your Name"
}

GET /api/v1/services

List all available services with required fields and pricing info.

GET /api/v1/health

Check if API is online.

Supported Services

Service	Description	Price	Batch
`ssn_dob`	SSN + DOB Lookup	$3.50	Up to 10
`dl`	Driver's License Lookup	$3.50	-
`cr`	Credit Report (PDF)
`cr2`	Credit Report (In-Depth, PDF)	$5.00	-
`credit_score`	Credit Score Check	$1.00	-
`phone`	Reverse Phone Lookup	$1.00	-

Required Fields by Service

SSN+DOB (`ssn_dob`)

Required: first_name, last_name, address, city, state, zip_code

Optional: force_refresh: true — skip local cache and force a fresh provider lookup (useful when older cached results may be missing fields like emails). Charges normally.

Returns: SSN, DOB, age, full name, aliases, address history with date ranges, phone numbers. May return multiple persons (2+) if more than one matches the address.

Note: driver license numbers and email addresses are NOT returned by this service. For DL lookups use the separate dl service.

{
    "api_key": "YOUR_KEY",
    "service": "ssn_dob",
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        "address": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62704"
    },
    "force_refresh": false
}

DL Lookup (`dl`)

Required: first_name, last_name, address, state

Returns: array of driver license numbers across states (a single person may have records in multiple states).

{
    "api_key": "YOUR_KEY",
    "service": "dl",
    "data": {
        "first_name": "Tommy",
        "last_name": "Garner",
        "address": "1978 Piedmont St",
        "state": "GA"
    }
}

Response:

{
    "status": "success",
    "service": "dl",
    "data": {
        "drivers_licenses": [
            {"number": "53515998",  "state": "GA"},
            {"number": "252437149", "state": "GA"},
            {"number": "10284566",  "state": "GA"},
            {"number": "90165004",  "state": "SC"}
        ]
    }
}

State format: full name (Georgia) or 2-letter code (GA) — both accepted.

Credit Report (`cr`)

Required: first_name, last_name, address, city, state, zip_code, dob, ssn

{
    "api_key": "YOUR_KEY",
    "service": "cr",
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        "address": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62704",
        "dob": "01/15/1990",
        "ssn": "123456789"
    }
}

Returns: a PDF file (application/pdf, Content-Disposition: attachment).
Filename: FirstName_LastName_Credit_Report.pdf
Save with curl:

curl -X POST https://172-86-89-201.nip.io/api/v1/lookup \
     -H "Content-Type: application/json" \
     -d '{ "api_key": "YOUR_KEY", "service": "cr", "data": { ... } }' \
     -OJ

If the report is not found, balance is refunded and a JSON error response is returned instead of a PDF.

Credit Report — In-Depth (`cr2`)

Required: first_name, last_name, address, city, state, zip_code, dob, ssn

{
    "api_key": "YOUR_KEY",
    "service": "cr2",
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        "address": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62704",
        "dob": "01/15/1990",
        "ssn": "123456789"
    }
}

Alternative provider to cr — same input fields, different upstream source (may return more in-depth report).
Returns: a PDF file (application/pdf, Content-Disposition: attachment).
Filename: FirstName_LastName_Credit_Report.pdf
Save with curl:

curl -X POST https://172-86-89-201.nip.io/api/v1/lookup \
     -H "Content-Type: application/json" \
     -d '{ "api_key": "YOUR_KEY", "service": "cr2", "data": { ... } }' \
     -OJ

If the report is not found, balance is refunded and a JSON error response is returned instead of a PDF.

Credit Score (`credit_score`)

Required: first_name, last_name, address, city, state, zip_code, dob

{
    "api_key": "YOUR_KEY",
    "service": "credit_score",
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        "address": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62704",
        "dob": "01/15/1990"
    }
}

Address: Do NOT use PO Box addresses.
Time: Takes 2-3 minutes to complete.

Reverse Phone Lookup (`phone`)

Required: phone (10-digit US number)

{
    "api_key": "YOUR_KEY",
    "service": "phone",
    "data": {
        "phone": "8587037723"
    }
}

Note: Can return multiple people associated with the phone number.

Response Examples

Success Response (SSN+DOB)

The data field is always an array of persons. The provider may return 1, 2, or more persons matching the same address.

{
    "status": "success",
    "service": "ssn_dob",
    "data": [
        {
            "name": "John A Doe",
            "ssn": "123-45-6789",
            "dob": "01/15/1990",
            "age": "35",
            "aliases": ["John Doe", "John Andrew Doe"],
            "address": "123 Main St; Springfield, IL 62704-1010 (01/01/2018 - 05/28/2026)",
            "addresses": [
                "123 Main St; Springfield, IL 62704-1010 (01/01/2018 - 05/28/2026)",
                "456 Oak Ave; Chicago, IL 60601 (06/01/2014 - 12/31/2017)"
            ],
            "phones": ["(555) 123-4567", "(555) 987-6543"]
        }
    ]
}

Field availability:

ssn, dob, name — usually present
age, aliases[], addresses[], phones[] — present when the provider has data; otherwise empty arrays
address — convenience copy of the most recent address (string)

Email addresses and driver license numbers are not returned by this service.

DL Response

{
    "status": "success",
    "service": "dl",
    "data": [
        {"number": "53515998", "state": "GA"},
        {"number": "252437149", "state": "GA"}
    ]
}

Credit Score Response

{
    "status": "success",
    "service": "credit_score",
    "data": {
        "credit_score": "783"
    }
}

Phone Lookup Response

{
    "status": "success",
    "service": "phone",
    "phone": "8587037723",
    "data": [
        {
            "name": "Youngjoo Kim",
            "address": "15642 Bernardo Center Dr",
            "city": "San Diego",
            "state": "CA",
            "zip": "92127",
            "age": "61"
        },
        {
            "name": "James Kim",
            "address": "15642 Bernardo Center Dr",
            "city": "San Diego",
            "state": "CA",
            "zip": "92127",
            "age": "35"
        }
    ]
}

Not Found Response

{
    "status": "not_found",
    "message": "No data found"
}

Balance is automatically refunded when data is not found.

Error Response

{
    "status": "error",
    "message": "Error description"
}

HTTP Status Codes

Code	Description
`200`	Success - data found
`400`	Bad request - missing parameters
`401`	Unauthorized - invalid API key
`402`	Payment required - insufficient balance
`404`	Not found - no data (balance refunded)
`500`	Server error

cURL Examples

Structured data:

curl -X POST https://172-86-89-201.nip.io/api/v1/lookup \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "service": "ssn_dob",
    "data": {
      "first_name": "John",
      "last_name": "Smith",
      "address": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip_code": "62704"
    }
  }'

Free-form text NEW:

curl -X POST https://172-86-89-201.nip.io/api/v1/lookup \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "service": "ssn_dob",
    "text": "John Smith\n123 Main St\nSpringfield\nIL\n62704"
  }'

Error Handling

The API validates all required fields before sending a request to the provider. If any required field is missing, the API returns an error with details about what's missing. No balance is deducted for validation errors.

HTTP Status Codes

Code	Meaning	Action Required
`200`	Success — data found	Display results
`400`	Bad request — parser could not extract required fields from text	Show `message` to user, ask to reformat
`402`	Insufficient balance	Top up balance
`404`	Not found — person not in database (balance refunded)	Show "Not Found"
`422`	Missing required fields in structured data	Show `missing_fields` to user
`429`	Rate limit exceeded (60 req/min)	Wait and retry
`500`	Provider error (balance refunded)	Retry later

Missing Fields Response (422)

When required fields are missing from structured data:

{
    "status": "error",
    "message": "Missing required fields: City, ZIP Code",
    "missing_fields": ["City", "ZIP Code"],
    "parsed": {
        "first_name": "John",
        "last_name": "Smith",
        "address": "123 Main St",
        "state": "NY"
    },
    "hint": "Please provide all required fields and try again."
}

Parse Error Response (400)

When using text and the parser cannot extract required fields:

{
    "status": "error",
    "message": "Could not extract required fields from text: last_name, state, zip",
    "parsed": {
        "first_name": "Dulce",
        "street": "2806 Quiet Meadows Dr",
        "city": "Houston"
    }
}

Required Fields by Service

Service	Required Fields
`ssn_dob`	first_name, last_name, address, city, state, zip_code
`dl`	first_name, last_name, address, zip_code, dob
`cr`	first_name, last_name, address, city, state, zip_code, dob, ssn
`cr2`	first_name, last_name, address, city, state, zip_code, dob, ssn
`credit_score`	first_name, last_name, address, city, state, zip_code, dob
`phone`	phone (10-digit US number)

Recommended Error Handling (Python example)

response = requests.post(url, json=payload)

if response.status_code == 200:
    data = response.json()["data"]
    # Display results to user

elif response.status_code == 422:
    error = response.json()
    missing = ", ".join(error["missing_fields"])
    print(f"Missing fields: {missing}")
    # Ask user to provide missing fields

elif response.status_code == 400:
    error = response.json()
    print(f"Error: {error['message']}")
    # Ask user to reformat input

elif response.status_code == 404:
    print("Person not found in database")
    # Balance was automatically refunded

elif response.status_code == 402:
    print("Insufficient balance, please top up")

Important Notes

Balance is deducted BEFORE the lookup
If data is NOT FOUND, balance is automatically REFUNDED
All transactions are logged
Keep your API key secure - do not share it
Credit Report (CR) returns a PDF file (binary) — save with curl -OJ or read raw bytes from the response body
Credit Report In-Depth (CR2) — same input as CR, alternative upstream provider, also returns a PDF file
Credit Score takes 2-3 minutes - the API call will wait for result

API Documentation

Base URL

Authentication

Flexible Input NEW

Supported input formats:

Supported DOB formats:

Example with text:

Endpoints

POST /api/v1/lookup

Option 1 — Structured data:

Option 2 — Free-form text NEW:

GET /api/v1/balance

Response:

GET /api/v1/services

GET /api/v1/health

Supported Services

Required Fields by Service

SSN+DOB (ssn_dob)

DL Lookup (dl)

Credit Report (cr)

Credit Report — In-Depth (cr2)

Credit Score (credit_score)

Reverse Phone Lookup (phone)

Response Examples

Success Response (SSN+DOB)

DL Response

Credit Score Response

Phone Lookup Response

Not Found Response

Error Response

HTTP Status Codes

cURL Examples

Structured data:

Free-form text NEW:

Error Handling

HTTP Status Codes

Missing Fields Response (422)

Parse Error Response (400)

Required Fields by Service

Recommended Error Handling (Python example)

Important Notes

SSN+DOB (`ssn_dob`)

DL Lookup (`dl`)

Credit Report (`cr`)

Credit Report — In-Depth (`cr2`)

Credit Score (`credit_score`)

Reverse Phone Lookup (`phone`)