API Documentation | IP Lookup & US Address Search Endpoints

Home / Documentation

Create API User POST /api/address-importer/users Address Search POST /api/address-importer/search City Search POST /api/address-importer/city-search Location Search POST /api/address-importer/location-search Distance Search POST /api/address-importer/distance-search Zipcode Radius Search POST /api/address-importer/zipcode-radius-search Email Risk Score POST /api/email-risk/score Email Risk Event POST /api/email-risk/events Calculate Distance POST /api/address-importer/calculate-distance GeoIP Lookup GET /api/geoip?ip=8.8.8.8 Zipcode Nearby Search GET /api/zipcode/zip_code?zip=10001&distance=10 Zip-to-Zip Distance GET /api/zipcode/distance?from_zip=10001&to_zip=10002 Lat/Lng to Zipcode GET /api/zipcode/zip?lat=40.7128&lng=-74.0060

Create API User

POST /api/address-importer/users

Create a new API user with the system token. The account starts inactive until email verification or admin activation is completed.

Payload / Parameters

`name` (required)
`email` (required, unique)
`phone` (optional)

$payload = [
    'name' => 'Client App',
    'email' => 'client@example.com',
    'phone' => '1234567890',
];

fetch('/api/address-importer/users', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_SYSTEM_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

requests.post(
    '/api/address-importer/users',
    headers={'Authorization': 'Bearer YOUR_SYSTEM_TOKEN'},
    json=payload,
)

{
  "message": "User created successfully. User is inactive by default.",
  "api_token": "PLAIN_TEXT_TOKEN"
}

Address Search

POST /api/address-importer/search

Search with `street`, `city`, `state`, `zipcode`, `country`, or a `full_address` string.

Payload / Parameters

`street`, `city`, `state`, `zipcode`, `country`
`full_address` for a one-field search
`limit` up to 100 results

$payload = ['street' => 'Main St', 'city' => 'Boston', 'state' => 'MA', 'limit' => 10];

fetch('/api/address-importer/search', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_ACTIVE_API_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({ street: 'Main St', city: 'Boston', state: 'MA', limit: 10 })
});

requests.post('/api/address-importer/search', headers=auth, json={'street': 'Main St', 'city': 'Boston', 'state': 'MA', 'limit': 10})

{
  "message": "Address search results.",
  "count": 2,
  "data": [{"full_address": "12 Main St, Boston, MA 02110, USA"}]
}

City Search

POST /api/address-importer/city-search

Lookup cities using a prefix string for autocomplete or location suggestions.

Payload / Parameters

`city` (required)
`limit` (optional)

$payload = ['city' => 'New', 'limit' => 10];

fetch('/api/address-importer/city-search', { method: 'POST', headers: auth, body: JSON.stringify({ city: 'New', limit: 10 }) });

requests.post('/api/address-importer/city-search', headers=auth, json={'city': 'New', 'limit': 10})

{
  "message": "City search results.",
  "count": 3,
  "data": [{"city": "New York", "state": "NY"}]
}

Location Search

POST /api/address-importer/location-search

Search around a latitude and longitude point with an optional radius.

Payload / Parameters

`latitude` and `longitude` (required)
`radius` and `limit` (optional)

$payload = ['latitude' => 40.7128, 'longitude' => -74.0060, 'radius' => 0.10, 'limit' => 10];

fetch('/api/address-importer/location-search', { method: 'POST', headers: auth, body: JSON.stringify({ latitude: 40.7128, longitude: -74.0060, radius: 0.10, limit: 10 }) });

requests.post('/api/address-importer/location-search', headers=auth, json={'latitude': 40.7128, 'longitude': -74.0060, 'radius': 0.10, 'limit': 10})

{
  "message": "Location search results.",
  "count": 1,
  "data": [{"full_address": "11 Broadway, New York, NY 10004, USA"}]
}

Distance Search

POST /api/address-importer/distance-search

Return address records that fall within a mile radius from a reference point.

Payload / Parameters

`latitude`, `longitude`, `distance_miles` (required)
`city`, `state`, `zipcode`, `country`, `limit` (optional)

$payload = ['latitude' => 29.7604, 'longitude' => -95.3698, 'distance_miles' => 5, 'city' => 'Houston'];

fetch('/api/address-importer/distance-search', { method: 'POST', headers: auth, body: JSON.stringify({ latitude: 29.7604, longitude: -95.3698, distance_miles: 5, city: 'Houston' }) });

requests.post('/api/address-importer/distance-search', headers=auth, json={'latitude': 29.7604, 'longitude': -95.3698, 'distance_miles': 5, 'city': 'Houston'})

{
  "message": "Distance search results.",
  "reference": {"latitude": 29.7604, "longitude": -95.3698},
  "count": 2,
  "data": [{"distance_miles": 1.24}]
}

Zipcode Radius Search

POST /api/address-importer/zipcode-radius-search

Find postal codes inside a target radius from a source zip code.

Payload / Parameters

`zipcode` and `distance_miles` (required)
`country`, `state`, `limit` (optional)

$payload = ['zipcode' => '10001', 'distance_miles' => 10, 'state' => 'NY', 'limit' => 50];

fetch('/api/address-importer/zipcode-radius-search', { method: 'POST', headers: auth, body: JSON.stringify({ zipcode: '10001', distance_miles: 10, state: 'NY', limit: 50 }) });

requests.post('/api/address-importer/zipcode-radius-search', headers=auth, json={'zipcode': '10001', 'distance_miles': 10, 'state': 'NY', 'limit': 50})

{
  "message": "Zipcode radius search results.",
  "count": 5,
  "data": [{"zipcode": "10002", "distance_miles": 2.47}]
}

Email Risk Score

POST /api/email-risk/score

Score an email address using syntax, DNS, MX, disposable, free-provider, role-based, gibberish, internal reputation, domain-age, and optional breach-history signals. The response includes a numeric score, risk band, decision, triggered signals, and detailed meta diagnostics.

Payload / Parameters

`email` (required)
`context` (optional, e.g. `b2b_signup`)
`meta` in the response includes domain age and optional breach-check details

$payload = ['email' => 'admin@10minutemail.com', 'context' => 'b2b_signup'];

            fetch('/api/email-risk/score', {
    method: 'POST',
    headers: { Authorization: 'Bearer YOUR_ACTIVE_API_TOKEN', 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: 'admin@10minutemail.com', context: 'b2b_signup' })
});

            requests.post('/api/email-risk/score', headers=auth, json={'email': 'admin@10minutemail.com', 'context': 'b2b_signup'})

{
    "message": "Email risk scored successfully.",
    "data": {
        "email": "admin@10minutemail.com",
        "normalized_email": "admin@10minutemail.com",
        "local_part": "admin",
        "domain": "10minutemail.com",
        "score": 85,
        "band": "very_high",
        "decision": "block",
        "signals": [
            "disposable_domain",
            "role_based_local_part"
        ],
        "meta": {
            "syntax_valid": true,
            "dns_found": true,
            "mx_found": true,
            "disposable": true,
            "free_provider": false,
            "role_based": true,
            "gibberish_local_part": false,
            "domain_age_days": 6200,
            "breach_check_enabled": false,
            "breach_count": null
        }
    }
}

Email Risk Event

POST /api/email-risk/events

Record reputation events such as `verified`, `abuse`, `bounce`, `chargeback`, or `otp_failed` so future scores reflect your own history.

Payload / Parameters

`email` (required)
`event_type` (required: verified, abuse, bounce, chargeback, otp_failed)
`source`, `context`, `occurred_at` (optional)

$payload = ['email' => 'customer@example.com', 'event_type' => 'verified', 'source' => 'signup_form'];

            fetch('/api/email-risk/events', {
    method: 'POST',
    headers: { Authorization: 'Bearer YOUR_ACTIVE_API_TOKEN', 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: 'customer@example.com', event_type: 'verified', source: 'signup_form' })
});

            requests.post('/api/email-risk/events', headers=auth, json={'email': 'customer@example.com', 'event_type': 'verified', 'source': 'signup_form'})

{
    "message": "Email risk event recorded successfully.",
    "data": {
        "id": 1,
        "email": "customer@example.com",
        "domain": "example.com",
        "event_type": "verified"
    }
}

Calculate Distance

POST /api/address-importer/calculate-distance

Directly calculate the miles between two coordinate pairs.

Payload / Parameters

`from_latitude`, `from_longitude`, `to_latitude`, `to_longitude` (required)

$payload = ['from_latitude' => 40.7128, 'from_longitude' => -74.0060, 'to_latitude' => 34.0522, 'to_longitude' => -118.2437];

fetch('/api/address-importer/calculate-distance', { method: 'POST', headers: auth, body: JSON.stringify({ from_latitude: 40.7128, from_longitude: -74.0060, to_latitude: 34.0522, to_longitude: -118.2437 }) });

requests.post('/api/address-importer/calculate-distance', headers=auth, json={'from_latitude': 40.7128, 'from_longitude': -74.0060, 'to_latitude': 34.0522, 'to_longitude': -118.2437})

{
  "message": "Distance calculated successfully.",
  "distance_miles": 2445.55
}

GeoIP Lookup

GET /api/geoip?ip=8.8.8.8

Resolve an IP address into geolocation and ASN metadata.

Payload / Parameters

`ip` query param (optional)
`fresh=1` to bypass cache

$ch = curl_init('/api/geoip?ip=8.8.8.8&fresh=1');

fetch('/api/geoip?ip=8.8.8.8&fresh=1', { headers: { Authorization: 'Bearer YOUR_ACTIVE_API_TOKEN' } });

requests.get('/api/geoip', headers=auth, params={'ip': '8.8.8.8', 'fresh': 1})

{
  "ok": true,
  "country_name": "United States",
  "city_name": "Mountain View"
}

Zipcode Nearby Search

GET /api/zipcode/zip_code?zip=10001&distance=10

Return zip codes found within the provided distance from a seed zip code.

Payload / Parameters

`zip` and `distance` query params are required

$ch = curl_init('/api/zipcode/zip_code?zip=10001&distance=10');

fetch('/api/zipcode/zip_code?zip=10001&distance=10', { headers: { Authorization: 'Bearer YOUR_ACTIVE_API_TOKEN' } });

requests.get('/api/zipcode/zip_code', headers=auth, params={'zip': 10001, 'distance': 10})

[{"zip": "10001", "distance": 0}, {"zip": "10002", "distance": 2.47}]

Zip-to-Zip Distance

GET /api/zipcode/distance?from_zip=10001&to_zip=10002

Measure the distance in miles between two zip codes.

Payload / Parameters

`from_zip` and `to_zip` query params are required

$ch = curl_init('/api/zipcode/distance?from_zip=10001&to_zip=10002');

fetch('/api/zipcode/distance?from_zip=10001&to_zip=10002', { headers: { Authorization: 'Bearer YOUR_ACTIVE_API_TOKEN' } });

requests.get('/api/zipcode/distance', headers=auth, params={'from_zip': 10001, 'to_zip': 10002})

2.47

Lat/Lng to Zipcode

GET /api/zipcode/zip?lat=40.7128&lng=-74.0060

Resolve coordinates into the nearest zip code list.

Payload / Parameters

`lat` and `lng` query params are required

$ch = curl_init('/api/zipcode/zip?lat=40.7128&lng=-74.0060');

fetch('/api/zipcode/zip?lat=40.7128&lng=-74.0060', { headers: { Authorization: 'Bearer YOUR_ACTIVE_API_TOKEN' } });

requests.get('/api/zipcode/zip', headers=auth, params={'lat': 40.7128, 'lng': -74.0060})

[{"zip": "10007", "distance": 0.18}]