Skip to main content
POST
Verify business

Authorizations

​
Authorization
string
header
required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Body

application/json
​
legal_name
string
required

Legal business name

Example:

"The Coca-Cola Company"

​
region
string
required

Region (state/province/county)

Example:

"GA"

​
reference_id
string

Your reference ID for tracking

Example:

"biz_12345"

​
workflow_key
string
default:business_verification_default

Workflow key to use for verification (determines required fields). If not provided, uses organization default.

Pattern: ^[a-z0-9_]+$
Example:

"business_verification_default"

​
ein
string

Employer Identification Number

Example:

"58-0628465"

​
entity_type
enum<string>

Entity type

Available options:
llc,
corporation,
lp,
llp,
nonprofit,
professional_llc,
professional_corporation,
other
Example:

"corporation"

​
registration_jurisdiction
string

Registration jurisdiction in ISO 3166-2 format (e.g., US-CA, US-NY, US-TX)

Example:

"US-FL"

​
formation_jurisdiction
string

Formation jurisdiction in ISO 3166-2 format (e.g., US-DE, US-CA, US-WY)

Example:

"US-DE"

​
formation_date
string<date>

Formation date (YYYY-MM-DD)

Example:

"1961-01-03"

​
address_line_1
string

Street address line 1

Example:

"One Coca-Cola Plaza NW"

​
address_line_2
string

Street address line 2

Example:

"Suite 100"

​
city
string

City

Example:

"Atlanta"

​
postal_code
string

Postal code

Example:

"30313"

​
country
string

Country (2-letter ISO code)

Example:

"US"

​
phone_number
string

Business phone number

Example:

"+15551234567"

​
email
string

Business email address

Example:

"contact@coca-cola.com"

​
website
string

Business website URL

Example:

"https://www.coca-cola.com"

​
associates
object[]

Associated people to verify

​
metadata
object

Custom metadata.

In test mode (sk_test_ key), business verification is always simulated — it never queries live registry, IRS, or any authoritative source, so no-directive test requests return a deterministic clean pass rather than real registry data. The reserved key _simulate selects the outcome. Value is <outcome>[:sync]:

  • Risk levels: low (default), medium, high, critical
  • Scenarios: inactive, newly_registered, tin_mismatch, no_match
  • fail → terminal status: failed
  • Resolves synchronously by default (mirroring the live fast-path). Append :async (e.g. low:async) to instead receive status: in_progress now and the result via the business.verification.completed webhook after a short delay.

Ignored in live mode.

Example:

Response

Verification accepted. Carries either a terminal outcome (status: completed — confident match OR "no match" with risk.level: critical + empty match) or an async-pending outcome (status: in_progress — final result delivered via the business.verification.completed webhook).

​
verification_id
string<uuid>
required

Unique verification ID

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
business_id
string<uuid>
required

ID of the business entity created or verified

Example:

"987e6543-e21a-45b6-c789-012345678901"

​
status
enum<string>
required

Current status of the verification. Branch on this before reading risk or match:

  • completed — Terminal. Either a confident match (populated match, evaluated risk.level) OR a "no match" verdict (empty match: {}, risk.level: critical with "Business not found" reason).
  • in_progress — Not yet resolved. risk.level is null; match may be empty or partial — treat both as unset until terminal. Final outcome delivered via business.verification.completed webhook.
  • failed — Terminal. The verification could not be completed. Safe to retry.
Available options:
pending,
in_progress,
completed,
failed
Example:

"completed"

​
mode
enum<string>
required

Test/live partition the verification was created under. Determined by the API key used.

Available options:
test,
live
Example:

"live"

​
risk
object
required

Business risk assessment. Only meaningful when status: completed. See BusinessVerificationRisk.level for the three response shapes (matched / no-match / async-pending).

​
match
object
required

Field-level match results against the matched authoritative record. On a matched terminal, every submitted field is present with an explicit result (match, partial_match, no_match, or not_checked) — never omitted. partial_match marks genuine near-matches (name variation/DBA, ±1-day formation date, address containment); formatting differences (abbreviations, ZIP+4) normalize to match. Empty (or near-empty) in two cases: (1) terminal "no match" outcome (status: completed, risk.level: critical) where no record was identified — a submitted ein still reports not_checked; (2) async-pending outcome (status: in_progress) where verification hasn't resolved yet — wait for the webhook. Only fields the partner submitted in the request ever appear.

​
created_at
string<date-time>
required

ISO 8601 timestamp of when the verification was created

Example:

"2025-10-24T10:30:00Z"

​
reference_id
string

Your reference ID (if provided in the request)

Example:

"biz_12345"

​
associates
object[]

Associated people verification results (full KYC results for each associate)

​
updated_at
string<date-time>

ISO 8601 timestamp of when the verification was last updated

Example:

"2025-10-24T10:35:00Z"