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.
| Field | Type | Required | Notes |
|---|---|---|---|
entity_name | string | yes | 2-200 chars |
state | string | yes | 2-letter US state code |
include_safer | boolean | no (default true) | Set false for non-trucking deals to skip the USDOT lookup |
include_ofac | boolean | no (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.
| Field | Type | Required | Notes |
|---|---|---|---|
entity_name | string | yes | 2-200 chars |
state | string | yes | 2-letter US state code |
entity_id | string | no | The entityId from /api/v1/lookup — pins the exact SOS record |
dot_number | string | no | Pins 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 |
branding | string | no (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.
| Provider | Per call | What's bundled |
|---|---|---|
| VerifySOS | Included — 3/day free, unlimited on Pro ($14.99/mo) | SOS + USDOT + OFAC |
| OpenCorporates | $0.10–$0.50 | SOS only |
| Cobalt Intelligence | $0.50–$2.00 | SOS + 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 →