Developer reference

API Documentation

Search the Recon data pool programmatically. Every endpoint takes a bearer key and returns predictable JSON, with unlimited searches on every key — no credits and nothing billed per request.

Authentication

Every request must include your secret key as a bearer token. Your key is shown exactly once when it is issued, so store it somewhere safe.

http

Authorization: Bearer recon_your_secret_key

There is no request quota and no per-lookup charge — a valid key can run unlimited searches. Fair-use burst limits still apply to protect the pool. Responses include X-RateLimit-Limit and X-RateLimit-Remaining; exceeding the limit returns 429 with Retry-After.

Search

Three endpoints share one request/response shape: /search/email, /search/phone, and /search/name (fuzzy, trigram-ranked).

POST/api/v1/search/{email|phone|name}

Body: query (required), country (optional ISO code), limit (optional, max 100).

Request

bash

curl -X POST https://reconenterprise.net/api/v1/search/email \
  -H "Authorization: Bearer recon_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "jane@example.com",
    "country": "US",
    "limit": 25
  }'

GET/api/v1/search/{email|phone|name}?q=…

The same lookup as a query string, handy for quick tests.

bash

curl "https://reconenterprise.net/api/v1/search/email?q=jane@example.com&country=US" \
  -H "Authorization: Bearer recon_your_secret_key"

Response

json

{
  "ok": true,
  "type": "email",
  "query": "jane@example.com",
  "normalized": "jane@example.com",
  "count": 1,
  "results": [
    {
      "id": "…",
      "country": "US",
      "email": "jane@example.com",
      "phone": "+14155550132",
      "firstName": "Jane",
      "lastName": "Smith",
      "fullName": "Jane Smith",
      "address": "500 Market St",
      "city": "San Francisco",
      "region": "CA",
      "postal": "94105",
      "extra": {}
    }
  ]
}

Bulk lookups

Submit a list and poll for the result. Provide either items (array) or text (newline or CSV string).

POST/api/v1/bulk

Returns 202 Accepted with a jobId.

Request

bash

curl -X POST https://reconenterprise.net/api/v1/bulk \
  -H "Authorization: Bearer recon_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "country": "AU",
    "items": ["a@example.com", "b@example.com"]
  }'

Response

json

{
  "ok": true,
  "jobId": "b1e2…",
  "status": "queued",
  "type": "email",
  "total": 2,
  "statusUrl": "/api/v1/bulk/b1e2…"
}

GET/api/v1/bulk/{jobId}

Poll job status; add ?download=1 once completed to fetch the CSV.

bash

curl https://reconenterprise.net/api/v1/bulk/b1e2… \
  -H "Authorization: Bearer recon_your_secret_key"

# When status is "completed", download the CSV:
curl -L "https://reconenterprise.net/api/v1/bulk/b1e2…?download=1" \
  -H "Authorization: Bearer recon_your_secret_key" -o results.csv

Country pools

Pass a country code to restrict a lookup to one pool. Omit it to search every pool at once.

United StatesUS

AustraliaAU

New ZealandNZ

CanadaCA

United KingdomGB

IrelandIE

Errors

Failures return { "ok": false, "error": "…" } with an appropriate HTTP status.

`400`	Validation failed - check the request body.
`401`	Missing, invalid, or revoked API key.
`404`	Job or resource not found for this key.
`429`	Rate limit exceeded - retry after the header interval.