Submit a bulk entity lookup job

Submit up to 1,000 entity lookups in a single request. Results are delivered via polling, webhook callback, or email. Each entity in the batch is billed at the standard lookup rate.

post/v1/bulk-lookup

Request

  • Base URL: https://api.opensosdata.com
  • URL: https://api.opensosdata.com/v1/bulk-lookup
  • Auth: API key in header x-api-key

Request body

source'auto' | 'cache' | 'live'

Data source preference applied to all entities in the batch

webhook_urlstring uri

URL to POST results when the job completes

email_resultsboolean

Email results CSV to your account email

search_by'debtor' | 'secured_party'

Search by debtor name (default) or secured party name. Secured party search is available in: AL, CA, CO, CT, FL, ID, KY, MA, MT, NC, RI, WV.

max_resultsinteger

Maximum number of results to return per entity (1-30)

cache_preference'cache_only' | 'cache_first' | 'live_only'

Fine-grained cache behavior. "cache_only" returns cached data or 404 (never scrapes). "cache_first" returns cache if available, otherwise scrapes live. "live_only" always scrapes live.

Response

Bulk job queued

job_idstring
statusstring
totalinteger

Number of entities in the batch

poll_urlstring

Example response

{
  "job_id": "bulk_abc123",
  "status": "queued",
  "poll_url": "/v1/bulk-lookup/bulk_abc123"
}

Changes

No recorded changes to this operation across all 1 revision of this API.