Skip to main content
POST
/
v1
/
business
Add a business
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    metadata: {
      external_id: 'user_789_in_my_system',
      customer_tier: 'standard',
      signup_source: 'web'
    },
    display_name: 'Acme Corp',
    vault: {
      'business.legal_name': 'Acme Corporation Inc.',
      'business.entity_type': 'llc',
      'business.formation_jurisdiction': 'US-DE',
      'business.formation_date': '2026-03-15',
      'business.address_line_1': '123 Business Blvd',
      'business.address_line_2': 'Suite 100',
      'business.city': 'Wilmington',
      'business.region': 'DE',
      'business.postal_code': '19801',
      'business.country': 'US'
    }
  })
};

fetch('https://api.getpalm.com/v1/business', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "business",
  "created_at": "2025-10-24T10:30:00Z",
  "updated_at": "2025-10-24T15:45:00Z",
  "metadata": {
    "external_id": "user_123_in_my_system",
    "customer_tier": "premium",
    "signup_source": "mobile_app"
  },
  "palm_id": "1234-5678-9012",
  "status": "active",
  "display_name": "Acme Corp",
  "ein_fingerprint": "c9f6ef5h141i49398hkm345621iii90jh3el0007",
  "verification": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "risk_level": "low",
    "workflow": {
      "name": "Business Verification",
      "version": 1
    },
    "executed_at": "2024-01-15T10:30:00.000Z"
  },
  "vault": {
    "business.legal_name": "Acme Corporation Inc.",
    "business.entity_type": "llc",
    "business.formation_jurisdiction": "US-DE",
    "business.formation_date": "2020-03-15",
    "business.address_line_1": "123 Main St",
    "business.city": "San Francisco",
    "business.region": "CA",
    "business.postal_code": "94105",
    "business.country": "US"
  }
}

Authorizations

​
Authorization
string
header
required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Body

application/json
​
metadata
object

Store up to 50 custom key-value pairs for application-specific data. Useful for storing references to external systems, feature flags, or other custom attributes.

Example:
{
  "external_id": "user_789_in_my_system",
  "customer_tier": "standard",
  "signup_source": "web"
}
​
display_name
string

Display name for the business

Example:

"Acme Corp"

​
vault
object

Business data to store in the vault. Use vault field IDs as keys (e.g., "business.ein", "business.legal_name"). See BusinessVaultFields for the complete list of available fields.

Example:
{
  "business.legal_name": "Acme Corporation Inc.",
  "business.entity_type": "llc",
  "business.formation_jurisdiction": "US-DE",
  "business.formation_date": "2026-03-15",
  "business.address_line_1": "123 Business Blvd",
  "business.address_line_2": "Suite 100",
  "business.city": "Wilmington",
  "business.region": "DE",
  "business.postal_code": "19801",
  "business.country": "US"
}

Response

201 - application/json

Business added

​
id
string<uuid>
required

Unique identifier for the resource

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
object
enum<string>
required

Object type identifier, always "business"

Available options:
business
Example:

"business"

​
created_at
string<date-time>
required

ISO 8601 timestamp of when the resource was created

Example:

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

​
updated_at
string<date-time>
required

ISO 8601 timestamp of when the resource was last updated

Example:

"2025-10-24T15:45:00Z"

​
metadata
object
required

Store up to 50 custom key-value pairs for application-specific data. Useful for storing references to external systems, feature flags, or other custom attributes.

Example:
{
  "external_id": "user_123_in_my_system",
  "customer_tier": "premium",
  "signup_source": "mobile_app"
}
​
palm_id
object
required

Palm identifier for the business, used for monitoring and external integrations

Example:

"1234-5678-9012"

​
status
enum<string>
required

Current status of the business

Available options:
active,
suspended,
deleted
Example:

"active"

​
display_name
object
required

Display name for the business

Example:

"Acme Corp"

​
ein_fingerprint
object
required

SHA-256 fingerprint of the business's EIN (Employer Identification Number). Used for duplicate detection and search without exposing the actual EIN. Automatically generated when EIN is stored in vault.

Example:

"c9f6ef5h141i49398hkm345621iii90jh3el0007"

​
verification
object
required

Most recent verification information. Null if business has never been verified.

​
vault
object
required

Cached vault field values for non-encrypted fields. Keys are full field IDs (e.g., "business.legal_name"). Only includes fields where encrypted=false in vault_field_definition.

Example:
{
  "business.legal_name": "Acme Corporation Inc.",
  "business.entity_type": "llc",
  "business.formation_jurisdiction": "US-DE",
  "business.formation_date": "2020-03-15",
  "business.address_line_1": "123 Main St",
  "business.city": "San Francisco",
  "business.region": "CA",
  "business.postal_code": "94105",
  "business.country": "US"
}