Skip to main content
POST
Verify existing business

Authorizations

Authorization
string
header
required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Path Parameters

business_id
string
required

Body

application/json
workflow_key
string

Workflow key to use for verification. If not provided, uses organization default.

Example:

"business_verification_default"

reference_id
string

Your reference ID for tracking this verification

Example:

"reverify_12345"

metadata
object

Additional metadata to attach to this verification

Example:

Response

201 - application/json
verification_id
string<uuid>
required

Unique verification ID

Example:

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

business_id
string
required

ID of the business entity created or verified

Example:

"bus_abc123"

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 is {}. Final outcome delivered via business.verification.completed webhook. Causes include async LLM disambiguation, status acquisition from live Secretary-of-State, or routing to manual review.
  • failed — System error. Safe to retry.
  • pending — Created but not yet started (rare; transient).
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 / pending).

match
object
required

Field-level match results against the matched authoritative record. Empty object {} in two cases: (1) terminal "no match" outcome (status: completed, risk.level: critical) where no record was identified; (2) async-pending outcome (status: in_progress) where verification hasn't resolved yet — wait for the webhook. When populated, only includes fields the partner submitted in the request.

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 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"