Verify business

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    workflow_key: 'business_verification_default',
    legal_name: 'The Coca-Cola Company',
    region: 'GA',
    reference_id: 'biz_12345',
    ein: '58-0628465',
    entity_type: 'corporation',
    registration_jurisdiction: 'US-FL',
    formation_jurisdiction: 'US-DE',
    formation_date: '1961-01-03',
    address_line_1: 'One Coca-Cola Plaza NW',
    address_line_2: 'Suite 100',
    city: 'Atlanta',
    postal_code: '30313',
    country: 'US',
    phone_number: '+15551234567',
    email: 'contact@coca-cola.com',
    website: 'https://www.coca-cola.com',
    associates: [
      {
        first_name: 'Jane',
        last_name: 'Smith',
        date_of_birth: '1985-05-20',
        ssn: '987-65-4321',
        address_line_1: '123 Main St',
        city: 'San Francisco',
        region: 'CA',
        postal_code: '94102',
        user_id: '123e4567-e89b-12d3-a456-426614174000',
        middle_name: 'M',
        email: 'jane.smith@example.com',
        phone_number: '+15559876543',
        address_line_2: 'Suite 100',
        country: 'US',
        ownership_percentage: 50,
        title: 'CEO'
      }
    ],
    metadata: {external_id: 'biz_789', source: 'onboarding_flow'}
  })
};

fetch('https://api.getpalm.com/v1/business/verification', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.getpalm.com/v1/business/verification"

payload = {
    "workflow_key": "business_verification_default",
    "legal_name": "The Coca-Cola Company",
    "region": "GA",
    "reference_id": "biz_12345",
    "ein": "58-0628465",
    "entity_type": "corporation",
    "registration_jurisdiction": "US-FL",
    "formation_jurisdiction": "US-DE",
    "formation_date": "1961-01-03",
    "address_line_1": "One Coca-Cola Plaza NW",
    "address_line_2": "Suite 100",
    "city": "Atlanta",
    "postal_code": "30313",
    "country": "US",
    "phone_number": "+15551234567",
    "email": "contact@coca-cola.com",
    "website": "https://www.coca-cola.com",
    "associates": [
        {
            "first_name": "Jane",
            "last_name": "Smith",
            "date_of_birth": "1985-05-20",
            "ssn": "987-65-4321",
            "address_line_1": "123 Main St",
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94102",
            "user_id": "123e4567-e89b-12d3-a456-426614174000",
            "middle_name": "M",
            "email": "jane.smith@example.com",
            "phone_number": "+15559876543",
            "address_line_2": "Suite 100",
            "country": "US",
            "ownership_percentage": 50,
            "title": "CEO"
        }
    ],
    "metadata": {
        "external_id": "biz_789",
        "source": "onboarding_flow"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.getpalm.com/v1/business/verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "workflow_key": "business_verification_default",
  "legal_name": "The Coca-Cola Company",
  "region": "GA",
  "reference_id": "biz_12345",
  "ein": "58-0628465",
  "entity_type": "corporation",
  "registration_jurisdiction": "US-FL",
  "formation_jurisdiction": "US-DE",
  "formation_date": "1961-01-03",
  "address_line_1": "One Coca-Cola Plaza NW",
  "address_line_2": "Suite 100",
  "city": "Atlanta",
  "postal_code": "30313",
  "country": "US",
  "phone_number": "+15551234567",
  "email": "contact@coca-cola.com",
  "website": "https://www.coca-cola.com",
  "associates": [
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "date_of_birth": "1985-05-20",
      "ssn": "987-65-4321",
      "address_line_1": "123 Main St",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94102",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "middle_name": "M",
      "email": "jane.smith@example.com",
      "phone_number": "+15559876543",
      "address_line_2": "Suite 100",
      "country": "US",
      "ownership_percentage": 50,
      "title": "CEO"
    }
  ],
  "metadata": {
    "external_id": "biz_789",
    "source": "onboarding_flow"
  }
}
'

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "business_id": "bus_abc123",
  "status": "completed",
  "mode": "live",
  "risk": {
    "level": "low",
    "reasons": [
      "Active UCC lien detected: $500,000 secured by Wells Fargo Bank",
      "Tax lien filed in Delaware: $25,000 owed to IRS",
      "Associate Jane Smith failed identity verification",
      "EIN issued less than 90 days ago",
      "Multiple bankruptcy filings in formation jurisdiction"
    ]
  },
  "match": {},
  "created_at": "2025-10-24T10:30:00Z",
  "reference_id": "biz_12345",
  "associates": [
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "verification_id": "660f9511-f30c-52e5-b827-557766551111",
      "status": "completed",
      "mode": "live",
      "risk": {
        "level": "low",
        "reasons": [
          "SSN first seen recently in bureau data",
          "Address mismatch detected",
          "High velocity on phone number (5 applications in 24 hours)",
          "Device fingerprint associated with known fraud",
          "Synthetic identity indicators detected with 85% confidence"
        ]
      },
      "match": {},
      "created_at": "2025-10-24T10:30:00Z",
      "reference_id": "user_12345",
      "synthetic": {
        "is_synthetic": false,
        "confidence_score": 15,
        "indicators": [
          "SSN issued after applicant date of birth",
          "Credit file recently established"
        ]
      },
      "velocity": {
        "email": 1,
        "phone": 2,
        "ssn": 1,
        "address": 3
      },
      "device": {
        "risk_score": 10,
        "is_emulator": false,
        "is_vpn": false,
        "is_proxy": false
      },
      "watchlist": {
        "status": "clear",
        "matches": [
          {
            "type": "sanctions",
            "name": "ofac_sdn",
            "confidence_score": 85
          }
        ]
      },
      "updated_at": "2025-10-24T10:35:00Z"
    }
  ],
  "updated_at": "2025-10-24T10:35:00Z"
}

{
  "type": "https://api.getpalm.com/problems/validation_error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/business/registry/search",
  "errors": [
    {
      "field": "name",
      "message": "name should not be empty",
      "code": "NOT_EMPTY"
    }
  ]
}

{
  "type": "https://api.getpalm.com/problems/authentication_error",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid authentication provided. Please provide one of the accepted authentication methods.",
  "instance": "/business/registry/search"
}

{
  "type": "https://api.getpalm.com/problems/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 60 seconds.",
  "instance": "/business/registry/search",
  "retry_after": 60,
  "limit": 100000,
  "remaining": 0,
  "reset": 1738540800
}

{
  "type": "https://api.getpalm.com/problems/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal server error occurred. Please contact support if this persists.",
  "instance": "/business/registry/search"
}

Verification

Verify business

Executes a configurable business verification workflow which utilizes authoritative sources (Secretary of State, IRS TIN matching, business registries), optionally verifies associated people, and returns risk assessment with field-level match results. The required fields are determined by the selected verification workflow.

Response status

The HTTP response is always 201; the verification outcome is carried by status in the body, so check it first.

completed — Resolved immediately. risk and match are populated: a confident match returns the agreeing fields and a risk level, while a no-match returns an empty match with risk.level: critical.
in_progress — Could not be resolved immediately and is continuing asynchronously; risk and match are not yet set. Wait for the business.verification.completed webhook, which delivers the final result in this same shape.
failed — A system error occurred (rare); safe to retry.

risk and match are only meaningful once status is completed.

POST

business

verification

Verify business

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    workflow_key: 'business_verification_default',
    legal_name: 'The Coca-Cola Company',
    region: 'GA',
    reference_id: 'biz_12345',
    ein: '58-0628465',
    entity_type: 'corporation',
    registration_jurisdiction: 'US-FL',
    formation_jurisdiction: 'US-DE',
    formation_date: '1961-01-03',
    address_line_1: 'One Coca-Cola Plaza NW',
    address_line_2: 'Suite 100',
    city: 'Atlanta',
    postal_code: '30313',
    country: 'US',
    phone_number: '+15551234567',
    email: 'contact@coca-cola.com',
    website: 'https://www.coca-cola.com',
    associates: [
      {
        first_name: 'Jane',
        last_name: 'Smith',
        date_of_birth: '1985-05-20',
        ssn: '987-65-4321',
        address_line_1: '123 Main St',
        city: 'San Francisco',
        region: 'CA',
        postal_code: '94102',
        user_id: '123e4567-e89b-12d3-a456-426614174000',
        middle_name: 'M',
        email: 'jane.smith@example.com',
        phone_number: '+15559876543',
        address_line_2: 'Suite 100',
        country: 'US',
        ownership_percentage: 50,
        title: 'CEO'
      }
    ],
    metadata: {external_id: 'biz_789', source: 'onboarding_flow'}
  })
};

fetch('https://api.getpalm.com/v1/business/verification', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.getpalm.com/v1/business/verification"

payload = {
    "workflow_key": "business_verification_default",
    "legal_name": "The Coca-Cola Company",
    "region": "GA",
    "reference_id": "biz_12345",
    "ein": "58-0628465",
    "entity_type": "corporation",
    "registration_jurisdiction": "US-FL",
    "formation_jurisdiction": "US-DE",
    "formation_date": "1961-01-03",
    "address_line_1": "One Coca-Cola Plaza NW",
    "address_line_2": "Suite 100",
    "city": "Atlanta",
    "postal_code": "30313",
    "country": "US",
    "phone_number": "+15551234567",
    "email": "contact@coca-cola.com",
    "website": "https://www.coca-cola.com",
    "associates": [
        {
            "first_name": "Jane",
            "last_name": "Smith",
            "date_of_birth": "1985-05-20",
            "ssn": "987-65-4321",
            "address_line_1": "123 Main St",
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94102",
            "user_id": "123e4567-e89b-12d3-a456-426614174000",
            "middle_name": "M",
            "email": "jane.smith@example.com",
            "phone_number": "+15559876543",
            "address_line_2": "Suite 100",
            "country": "US",
            "ownership_percentage": 50,
            "title": "CEO"
        }
    ],
    "metadata": {
        "external_id": "biz_789",
        "source": "onboarding_flow"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.getpalm.com/v1/business/verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "workflow_key": "business_verification_default",
  "legal_name": "The Coca-Cola Company",
  "region": "GA",
  "reference_id": "biz_12345",
  "ein": "58-0628465",
  "entity_type": "corporation",
  "registration_jurisdiction": "US-FL",
  "formation_jurisdiction": "US-DE",
  "formation_date": "1961-01-03",
  "address_line_1": "One Coca-Cola Plaza NW",
  "address_line_2": "Suite 100",
  "city": "Atlanta",
  "postal_code": "30313",
  "country": "US",
  "phone_number": "+15551234567",
  "email": "contact@coca-cola.com",
  "website": "https://www.coca-cola.com",
  "associates": [
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "date_of_birth": "1985-05-20",
      "ssn": "987-65-4321",
      "address_line_1": "123 Main St",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94102",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "middle_name": "M",
      "email": "jane.smith@example.com",
      "phone_number": "+15559876543",
      "address_line_2": "Suite 100",
      "country": "US",
      "ownership_percentage": 50,
      "title": "CEO"
    }
  ],
  "metadata": {
    "external_id": "biz_789",
    "source": "onboarding_flow"
  }
}
'

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "business_id": "bus_abc123",
  "status": "completed",
  "mode": "live",
  "risk": {
    "level": "low",
    "reasons": [
      "Active UCC lien detected: $500,000 secured by Wells Fargo Bank",
      "Tax lien filed in Delaware: $25,000 owed to IRS",
      "Associate Jane Smith failed identity verification",
      "EIN issued less than 90 days ago",
      "Multiple bankruptcy filings in formation jurisdiction"
    ]
  },
  "match": {},
  "created_at": "2025-10-24T10:30:00Z",
  "reference_id": "biz_12345",
  "associates": [
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "verification_id": "660f9511-f30c-52e5-b827-557766551111",
      "status": "completed",
      "mode": "live",
      "risk": {
        "level": "low",
        "reasons": [
          "SSN first seen recently in bureau data",
          "Address mismatch detected",
          "High velocity on phone number (5 applications in 24 hours)",
          "Device fingerprint associated with known fraud",
          "Synthetic identity indicators detected with 85% confidence"
        ]
      },
      "match": {},
      "created_at": "2025-10-24T10:30:00Z",
      "reference_id": "user_12345",
      "synthetic": {
        "is_synthetic": false,
        "confidence_score": 15,
        "indicators": [
          "SSN issued after applicant date of birth",
          "Credit file recently established"
        ]
      },
      "velocity": {
        "email": 1,
        "phone": 2,
        "ssn": 1,
        "address": 3
      },
      "device": {
        "risk_score": 10,
        "is_emulator": false,
        "is_vpn": false,
        "is_proxy": false
      },
      "watchlist": {
        "status": "clear",
        "matches": [
          {
            "type": "sanctions",
            "name": "ofac_sdn",
            "confidence_score": 85
          }
        ]
      },
      "updated_at": "2025-10-24T10:35:00Z"
    }
  ],
  "updated_at": "2025-10-24T10:35:00Z"
}

{
  "type": "https://api.getpalm.com/problems/validation_error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/business/registry/search",
  "errors": [
    {
      "field": "name",
      "message": "name should not be empty",
      "code": "NOT_EMPTY"
    }
  ]
}

{
  "type": "https://api.getpalm.com/problems/authentication_error",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid authentication provided. Please provide one of the accepted authentication methods.",
  "instance": "/business/registry/search"
}

{
  "type": "https://api.getpalm.com/problems/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 60 seconds.",
  "instance": "/business/registry/search",
  "retry_after": 60,
  "limit": 100000,
  "remaining": 0,
  "reset": 1738540800
}

{
  "type": "https://api.getpalm.com/problems/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal server error occurred. Please contact support if this persists.",
  "instance": "/business/registry/search"
}

Authorizations

Authorization

string

header

required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Body

application/json

workflow_key

string

default:business_verification_default

required

Workflow key to use for verification (determines required fields)

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

Example:

"business_verification_default"

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"

ein

string

Employer Identification Number

Example:

"58-0628465"

entity_type

enum<string>

Entity type

Available options:

llc,

corporation,

lp,

llp,

nonprofit,

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"

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

Show child attributes

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, sanctions, lien, tin_mismatch, no_match
fail → terminal status: failed
Append :sync (e.g. low:sync) to complete synchronously; otherwise the result is delivered asynchronously via the business.verification.completed webhook after a short delay.

Ignored in live mode.

Example:

{
  "external_id": "biz_789",
  "source": "onboarding_flow"
}

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

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).

Show child attributes

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.

Show child attributes

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)

Show child attributes

updated_at

string<date-time>

ISO 8601 timestamp of when the verification was last updated

Example:

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

Check business name eligibility

Verify TIN

⌘I