API Documentation

Authentication

All customer API requests authenticate with an api_key query or form/body parameter. There is no User-Agent restriction — library defaults (python-requests, curl, etc.) work fine.

https://search-api.dev

curl "https://search-api.dev/?api_key=YOUR_API_KEY&phone=1234567890"

Also see the interactive OpenAPI UI at /api-reference and this page at /docs.

Unified Search Endpoint

Search by email, phone, domain, or company on a single endpoint. The API detects the search type from the parameters you send.

GET / or POST /

Parameters

* Provide exactly one primary lookup: phone, email, domain, or company.

Example Request

curl "https://search-api.dev/?api_key=YOUR_KEY&phone=%2B11234567890&extra_info=true"

Response Example

{
  "found": true,
  "data": {
    "name": "John Doe",
    "dob": "1980-01-01",
    "age": 44,
    "numbers": [{"number": "+1234567890", "carrier_name": "Verizon Wireless"}],
    "emails": ["[email protected]"],
    "addresses": ["123 Main St, New York, NY 10001"]
  },
  "_pricing": {
    "base_cost": 0.0025,
    "total_cost": 0.0045  }
}

Phone Search

Search for person details using a phone number. Supports enrichment with property values, carrier info, and extra data.

Parameters

search:phone

Email Search

Search for person details using an email address.

Parameters

search:email

TLO Enrichment

TLO (Telecommunications Lookup) Enrichment provides comprehensive person data enrichment by matching your search results with additional information from InstantCheckmate. This includes historical data, related persons, criminal records, confirmed phone numbers, and more.

Requirements

TLO enrichment requires the following information to be available from your search results:

• First Name - Required
• Last Name - Required
• City - Required
• State - Required
• Middle Name - Optional (helps narrow down results)

Note: TLO enrichment is only charged if an enrichment request can be made (all required fields are present). If the required fields are missing, the parameter is ignored and no charge is applied.

What TLO Enrichment Provides

Data Matching & Quality

TLO enrichment uses intelligent matching to ensure data accuracy:

• Match Scoring - Uses name, phone, address, and DOB matching with configurable weights
• Minimum Match Score - Only returns data when match confidence is ≥ 50%
• Definite Match - When exact name + last 4 phone digits match, prioritizes your dataset's DOB
• Data Merging - Intelligently merges TLO data with existing data, preserving all original information (carrier info, zestimate, etc.)
• DOB Filtering - Automatically filters out DOBs that are inconsistent with the primary DOB (age difference > 10 years)

Response Example

{
  "email": "[email protected]",
  "name": "John Doe",
  "dob": "1980-01-01",
  "age": 44,
  "numbers": ["+1234567890", "XXXXXX1234"],
  "confirmed_numbers": ["+1234567890"],
  "phone_numbers_full": [
    {
      "number": "+1234567890",
      "line_type": "Mobile",
      "carrier": "VERIZON WIRELESS",
      "date_first_seen": {"date": {"month": 1, "day": 15, "year": 2010}},
      "is_spam_report": false
    },
    {
      "number": "XXXXXX1234",
      "line_type": "Landline",
      "carrier": "AT&T",
      "date_first_seen": {"date": {"month": 3, "day": 20, "year": 2005}},
      "is_spam_report": false
    }
  ],
  "all_names": [
    {"name": "John Doe"},
    {
      "name": "John Michael Doe",
      "first": "John",
      "middle": "Michael",
      "last": "Doe",
      "date_first_seen": {"date": {"month": 6, "day": 1, "year": 2008}},
      "date_last_seen": {"date": {"month": 12, "day": 31, "year": 2024}}
    }
  ],
  "all_dobs": [
    {
      "dob": "1980-01-01",
      "age": 44,
      "date": {"month": 1, "day": 1, "year": 1980}
    }
  ],
  "related_persons": [
    {
      "name": "Jane Doe",
      "dob": "1982-05-15",
      "age": 42,
      "relationship": "Spouse",
      "sub_type": "Spouse",
      "addresses": ["123 Main St, New York, NY 10001"]
    }
  ],
  "criminal_records": [
    {
      "source_name": "NEW YORK COUNTY COURT",
      "source_state": "NY",
      "case_numbers": ["12345"],
      "crimes": [
        {
          "case_number": "12345",
          "crime_type": "Traffic",
          "crime_county": "New York",
          "offense_code": "SPEEDING",
          "charges_filed_date": "2015-06-10"
        }
      ]
    }
  ],
  "_pricing": {
    "search_cost": 0.0025,
    "tlo_enrichment_cost": 0.0030,
    "total_cost": 0.0055  }
}

Usage

curl "https://search-api.dev/[email protected]&tlo_enrichment=1"

Phone Recovery Verification

Phone Recovery Verification verifies phone numbers associated with email addresses by checking various email provider recovery systems. This feature is only available for email searches and helps confirm if a phone number is linked to an email account.

Enabling Recovery Verification

To enable Phone Recovery Verification for an email search, simply add the recovery_check parameter to your request:

When enabled, phone numbers are automatically extracted from the email search results and verified against the email provider's recovery systems. You don't need to provide phone numbers manually.

Module Order Configuration

You can optionally specify which recovery modules to run and in what order for a specific request. If not specified, the system will automatically use the module order saved in your profile settings.

recovery_modules[module_order][]=yahoo&recovery_modules[module_order][]=outlook&recovery_modules[module_order][]=icloud
recovery_modules[enabled_modules][]=yahoo&recovery_modules[enabled_modules][]=outlook

{
  "recovery_modules": {
    "module_order": ["yahoo", "outlook", "icloud"],
    "enabled_modules": ["yahoo", "outlook"]
  }
}

Parameters

How It Works

Phone Recovery Verification works by:

1. Performing the email search and extracting phone numbers from the search results automatically
2. Processing the email address through multiple email provider recovery systems (iCloud, Outlook, Yahoo, AOL, Xfinity/Comcast, GMX/Mail.com, DoorDash, etc.) in the specified order
3. Each provider module checks if the email account has a recovery phone number registered
4. If a recovery phone number is found, it's compared against the phone numbers extracted from the search results
5. Processing stops on the first successful match, or continues through all enabled modules if no match is found
6. Only modules that support the email domain are executed (e.g., Yahoo module only runs for yahoo.com emails)

Supported Email Providers

Pricing

Phone Recovery Verification is charged per module executed. Each module has its own pricing:

Important: You are only charged for modules that are actually executed. Modules that don't support the email domain are automatically skipped and not charged.

Example Requests

Basic Request (uses profile settings):

curl "https://search-api.dev/[email protected]&recovery_check=1"

Request with Custom Module Order:

curl "https://search-api.dev/[email protected]&recovery_check=1&recovery_modules[module_order][]=yahoo&recovery_modules[module_order][]=outlook&recovery_modules[enabled_modules][]=yahoo&recovery_modules[enabled_modules][]=outlook"

Response Example

{
  "found": true,
  "data": {
    "name": "John Doe",
    "email": "[email protected]",
    "numbers": ["+1234567890"]
  },
  "recovery_check": {
    "matched": true,
    "matched_number": "+1234567890",
    "matched_module": "yahoo",
    "modules_used": ["yahoo", "icloud", "outlook"],
    "cost": 0.003
  },
  "_pricing": {
    "base_cost": 0.0025,
    "recovery_check": 0.003,
    "total_cost": 0.0055  }
}

Response Fields

search:email

Standalone recovery check

If you already have an email and phone list, call recovery without a full person search:

GET or POST /?action=recovery-check

curl -X POST "https://search-api.dev/?api_key=YOUR_KEY&action=recovery-check" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","numbers":["+11234567890"]}'

List recovery modules

GET /?action=get_recovery_modules&api_key=YOUR_KEY

Returns available modules and current per-module pricing.

Domain Search

Search for contacts associated with a domain name. Priced at the domain search rate ($4.0000).

Parameters

search:domain

curl "https://search-api.dev/?api_key=YOUR_KEY&domain=example.com"

Company Search

Find people associated with a company name. Same price and similar result shape as domain search ($4.0000). Overly broad terms (e.g. generic words like “company”) are rejected.

search:domain

curl "https://search-api.dev/?api_key=YOUR_KEY&company=Acme%20Corp&country=United%20States"

Carrier Lookup

Look up carrier / line data for a phone number without running a full person search. Charged at the carrier rate ($0.0005) when a successful lookup is returned.

GET /?action=carrier_lookup or POST /?action=carrier_lookup

curl "https://search-api.dev/?api_key=YOUR_KEY&action=carrier_lookup&phone=%2B11234567890"

{
  "success": true,
  "data": { "carrier_name": "Verizon Wireless", "line_type": "Mobile" },
  "cost": 0.0005}

Person Report & Identity Verify

Run a normal search and optionally reshape the response with action.

Person report

Add action=person_report with your usual email / phone / domain / company lookup. The search runs as usual, then the payload is normalized into a person-report structure.

curl "https://search-api.dev/[email protected]&action=person_report"

Verify identity

Add action=verify_identity. Include name (and your lookup field) to receive a verification-oriented response comparing the search hit to the provided identity fields.

curl "https://search-api.dev/[email protected]&name=John%20Doe&action=verify_identity"

Batch API

Run up to 100 searches in one request. Send a JSON array as the request body. Each item is billed like an individual search (email/phone base + add-ons, or domain/company rate).

POST /?action=batch&api_key=YOUR_KEY

[
  { "email": "[email protected]", "extra_info": true },
  { "phone": "+11234567890", "carrier_info": true },
  { "domain": "example.com" },
  { "company": "Acme Corp", "country": "United States" }
]

curl -X POST "https://search-api.dev/?api_key=YOUR_KEY&action=batch" \
  -H "Content-Type: application/json" \
  -d '[{"email":"[email protected]"},{"phone":"+11234567890"}]'

Balance is checked against the estimated batch cost before processing. Max batch size: 100.

Billing & Balance

Get Account Balance

GET /?action=get_balance

billing:view

curl "https://search-api.dev/?api_key=YOUR_KEY&action=get_balance"

{
  "balance": 123.45
}

Organization Controls

Manage organization-wide API consumption by capping how much balance any individual API key can spend. These endpoints are only available to organization API keys with one of the following scopes: api:usage, api:* , api.manage, api:create, or billing:manage.

Organization-capable endpoints:

• GET /?action=get_balance – retrieve pooled organization balance.
• GET /?action=get_usage_stats – organization-wide usage rollups.
• GET /?action=get_access_logs – audit searches performed by your team.
• GET/POST /?action=batch – batch searches billed against the organization.
• POST /?action=update_api_key_usage – enforce per-key usage caps (described below).

Update API Key Usage & Limits

POST /?action=update_api_key_usage

At least one of usage or max_usage must be provided. If a max usage is configured, searches will be blocked once the tracked usage reaches the cap. Set usage to 0 to reset a key after reconciliation.

curl -X POST "https://search-api.dev/?api_key=ORG_MASTER_KEY&action=update_api_key_usage" \
  -H "Content-Type: application/json" \
  -d '{
    "target_api_key": "TEAM_MEMBERS_KEY",
    "max_usage": 25,
    "usage": 12.5
}'

{
  "success": true,
  "target_api_key": "TEAM_MEM...",
  "balance_usage": 12.5,
  "max_balance_usage": 25
}

Analytics & Usage

Get Usage Statistics

GET /?action=get_usage_stats

curl "https://search-api.dev/?api_key=YOUR_KEY&action=get_usage_stats"

{
  "usage_stats": {
    "today": { "searches": 12, "cost": 0.03 },
    "total": { "searches": 1500, "cost": 3.75 }
  }
}

Get Access Logs

GET /?action=get_access_logs

curl "https://search-api.dev/?api_key=YOUR_KEY&action=get_access_logs&limit=50"

Get Cache Statistics

GET /?action=cache_stats

Returns cache-related statistics for the account/key.

Refresh Balance Cache

GET /?action=refresh_balance_cache

Forces a refresh of the cached balance reading for the API key.

Dashboard Bulk Search

For API-key batching, use Batch API. The dashboard bulk uploader is session-authenticated (logged into the web UI), not API-key based.

Upload Bulk Search File

POST /dashboard/bulk-search/upload

Note: Requires a logged-in dashboard session.

Download Results

GET /dashboard/bulk-search/download/{id}?format={csv|json}

Pricing

* Phone Recovery Verification pricing varies by module ($0.001 - $0.003 per module). You are only charged for modules that are actually executed. See Phone Recovery Verification section for details.

Note: Failed searches (e.g., insufficient balance, invalid input) are logged but not billed.

API Scopes

API keys can be restricted to specific scopes for security. Available scopes:

Search Scopes

• search:phone - Phone number searches
• search:email - Email address searches
• search:domain - Domain and company searches
• search:bulk - Bulk search operations
• search:* - All search operations

Empty scopes on a key mean unrestricted (backward compatible). Dot forms like search.email are also accepted.

API Management Scopes

• api:view - View API keys
• api:create - Create API keys
• api:revoke - Revoke/delete API keys
• api:* - Full API key management

Billing Scopes

• billing:view - View billing information
• billing:manage - Create and manage payments
• billing:* - Full billing access

Analytics Scopes

• analytics:basic - Basic analytics (usage stats, access logs)
• analytics:advanced - Advanced analytics (cache stats, exports)
• analytics:* - Full analytics access

Error Codes

Error Response Format

{
  "error": "Error message",
  "message": "Detailed error description",
  "required_permission": "search.phone"  // For 403 errors
}