2026 offer: free accounts get unlimited searches and reports through December 31. Create your free account →
REST API · v1 · OpenAPI 3.0

One call. SOS + USDOT + OFAC. Included with your account.

Every /api/v1/lookup returns the Secretary of State entity record (or a direct link to it), USDOT/FMCSA carrier data, and OFAC SDN screening — bundled into a single JSON response. Built for commercial-finance underwriting, fraud teams, and developers building KYB flows.

Quick start

# Get your API key at /account/api-key
KEY="vfs_your_key_here"

curl -X POST https://verifysos.com/api/v1/lookup \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_name": "JNG Trucking LLC",
    "state": "CA",
    "include_safer": true
  }'

Sample response (200)

{
  "success": true,
  "data": {
    "state": "CA",
    "entityName": "JNG TRUCKING LLC",
    "entityId": "202359218946",
    "status": "ACTIVE",
    "entityType": "Limited Liability Company - CA",
    "formationDate": "2023-10-03",
    "yearsInBusiness": 2,
    "registeredAgent": {
      "name": "JUAN NAVARRO GONZALEZ",
      "address": "18126 10TH ST, BLOOMINGTON, CA 92316"
    },
    "principalAddress": "18126 10TH ST, BLOOMINGTON, CA 92316",
    "officers": [
      {"name": "JUAN NAVARRO GONZALEZ", "title": "MANAGER"}
    ],
    "sosUrl": "https://bizfileonline.sos.ca.gov/search/business/...",
    "usdot": {
      "dotNumber": "4142050",
      "mcNumber": "MC-1588327",
      "status": "ACTIVE",
      "legalName": "JNG TRUCKING LLC",
      "physicalAddress": "BLOOMINGTON, CA",
      "fleetSize": 1
    },
    "ofac": { "clear": true, "hits": [] }
  },
  "cost": 0,
  "scraped_at": "2026-05-28T16:42:11Z"
}

Roadmap — coming soon

Today the API returns SOS entity records, USDOT/FMCSA carrier data, and OFAC screening. These data sources are on the roadmap and will be added to the same /api/v1/lookup response as they ship (until then the ucc and licenses fields are null):

  • UCC liens — secured-filing / lien search
  • Contractor & pro-licenses — state contractor + professional-license registries
  • NPI registry — healthcare-provider NPI
  • Federal contracts — SAM.gov / USAspending federal award data
  • Cross-state owner graph — link an owner / address across states

Rate limits

Each API key is rate-limited to 60 requests per minute, on every plan. Need more throughput? Contact us at [email protected].

Successful (200) and rate-limited (429) responses include the standard X-RateLimit-* headers so your client can throttle gracefully:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1748470823
Retry-After: 18   (only on 429)

A 429 Too Many Requests response includes Retry-After in seconds — wait that long, then retry.

Endpoints

POST /api/v1/lookup

Look up a business entity by name + state. Bundles USDOT/OFAC.

FieldTypeRequiredNotes
entity_namestringyes2-200 chars
statestringyes2-letter US state code
include_saferbooleanno (default true)Set false for non-trucking deals to skip the USDOT lookup
include_ofacbooleanno (default true)Always runs — flag retained for compatibility

200 — Entity found. 404 — Not found (counts toward a free account's 3 a day). 400 — Bad request. 401 — Missing or invalid x-api-key. 402 — Free account's 3 daily lookups used; Pro is unlimited. 429 — Over 60 requests/minute; wait Retry-After seconds. 500 — Scraper error (not counted).

POST /api/v1/package

Builds the full document package — cover sheet, Secretary of State printout and USDOT/SAFER snapshot, merged into one PDF — exactly as the website generates it, and returns the PDF itself (application/pdf). Held under 60 seconds from search to finished package.

FieldTypeRequiredNotes
entity_namestringyes2-200 chars
statestringyes2-letter US state code
entity_idstringnoThe entityId from /api/v1/lookup — pins the exact SOS record
dot_numberstringnoPins the USDOT carrier. Without it the DOT section is included only on a confident match (one active carrier, name match, same address state as the SOS principal address); otherwise omitted, and X-Safer-Note says why
brandingstringno (default standard)plain = the identical package with no VerifySOS name, logo, URL or footer anywhere in the PDF
curl -X POST https://verifysos.com/api/v1/package \
  -H "x-api-key: vfs_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"entity_name": "JNG Trucking LLC", "state": "CA", "branding": "plain"}' \
  -D headers.txt -o package.pdf

Match details come back in response headers:

X-Entity-Name: JNG TRUCKING LLC
X-Entity-Id: 202330110001
X-Status: Active
X-Usdot: 1234567          (empty when no DOT section)
X-Safer-Included: true
X-Safer-Note: included: USDOT 1234567 (name + CA address match)
X-Owners-Count: 2
X-Document-Count: 3
X-Branding: plain

200 — The PDF. 404 — No SOS match, or entity_id no longer in the results (entity_id_not_found). 400 / 401 / 402 / 429 — As for lookup; a package counts toward the same daily allowance. 503 — The state's site is down or all builders are busy; retry after Retry-After (not counted).

GET /api/v1/states

Returns every supported state + automation status. No auth required.

{
  "success": true,
  "count": 51,
  "states": [
    {"code": "AK", "name": "Alaska", "status": "active",
     "landingUrl": "https://verifysos.com/states/alaska"},
    ...
  ]
}

GET /api/v1/health

Lightweight health check. Returns version + commit SHA. No auth.

Pricing

  • API access is included with your VerifySOS account — 3 lookups a day free, unlimited on Pro ($14.99/mo)
  • No per-lookup fees — every call covers SOS + USDOT + OFAC in one response
  • 60 requests/minute per key — the same on every plan
  • Pro, $14.99/mo — unlimited verification reports and API lookups. 7-day free trial. Cancel anytime.

Other SOS APIs make you pay per call AND give you raw SOS JSON only — no USDOT, no OFAC. We bundle SOS + USDOT + OFAC into the same response with no per-lookup fees, included with your account — purpose-built for credit underwriting on trucking + construction + transportation deals.

ProviderPer callWhat's bundled
VerifySOSIncluded — 3/day free, unlimited on Pro ($14.99/mo)SOS + USDOT + OFAC
OpenCorporates$0.10–$0.50SOS only
Cobalt Intelligence$0.50–$2.00SOS + officers
Middesk$1.00+SOS + KYB orchestration

Coverage

Real-time lookups across all 50 states. USDOT/FMCSA covers all 50 states. Secretary of State lookups are live in most states; elsewhere the response's sosUrl is a direct link to the official state business search. Pass any of these state codes:

Ready to integrate?

Sign up for an account, generate an API key, start making calls — 3 lookups a day free.

Create an account →

Report a bug — straight to our team

See something broken or weird? Tell us. Your report submits directly to our team — no email client needed. Each report gets a unique ticket ID so we can track and respond.