Apply for an EIN

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    business_id: '987e6543-e21a-45b6-c789-012345678901',
    responsible_party: {
      user_id: '123e4567-e89b-12d3-a456-426614174000',
      first_name: 'Jane',
      last_name: 'Doe',
      ssn: '123-45-6789'
    },
    reason: 'started_new_business',
    fiscal_year_end_month: 12,
    expected_employee_count: {agricultural: 0, other: 5},
    principal_activity: {category: 'accommodations', type: 'hotel'},
    principal_activity_detail: 'Software consulting services',
    has_previous_ein: false,
    reason_detail: 'Compliance with state reporting requirements',
    wage_date: '2026-04-01',
    previous_ein: '12-3456789',
    trade_name: 'Acme Trading Co',
    form_944_election: false,
    llc_member_count: 1,
    members_are_married_couple: false,
    llc_classification: 'single_member',
    metadata: {internal_ref: 'REF-123'}
  })
};

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

import requests

url = "https://api.getpalm.com/v1/filing/ein"

payload = {
    "business_id": "987e6543-e21a-45b6-c789-012345678901",
    "responsible_party": {
        "user_id": "123e4567-e89b-12d3-a456-426614174000",
        "first_name": "Jane",
        "last_name": "Doe",
        "ssn": "123-45-6789"
    },
    "reason": "started_new_business",
    "fiscal_year_end_month": 12,
    "expected_employee_count": {
        "agricultural": 0,
        "other": 5
    },
    "principal_activity": {
        "category": "accommodations",
        "type": "hotel"
    },
    "principal_activity_detail": "Software consulting services",
    "has_previous_ein": False,
    "reason_detail": "Compliance with state reporting requirements",
    "wage_date": "2026-04-01",
    "previous_ein": "12-3456789",
    "trade_name": "Acme Trading Co",
    "form_944_election": False,
    "llc_member_count": 1,
    "members_are_married_couple": False,
    "llc_classification": "single_member",
    "metadata": { "internal_ref": "REF-123" }
}
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/filing/ein \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_id": "987e6543-e21a-45b6-c789-012345678901",
  "responsible_party": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "Jane",
    "last_name": "Doe",
    "ssn": "123-45-6789"
  },
  "reason": "started_new_business",
  "fiscal_year_end_month": 12,
  "expected_employee_count": {
    "agricultural": 0,
    "other": 5
  },
  "principal_activity": {
    "category": "accommodations",
    "type": "hotel"
  },
  "principal_activity_detail": "Software consulting services",
  "has_previous_ein": false,
  "reason_detail": "Compliance with state reporting requirements",
  "wage_date": "2026-04-01",
  "previous_ein": "12-3456789",
  "trade_name": "Acme Trading Co",
  "form_944_election": false,
  "llc_member_count": 1,
  "members_are_married_couple": false,
  "llc_classification": "single_member",
  "metadata": {
    "internal_ref": "REF-123"
  }
}
'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "filing",
  "mode": "live",
  "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"
  },
  "jurisdiction": "US-NC",
  "name": "Acme Holdings LLC",
  "expedited_tier": "same_day",
  "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "result": {
    "registration_number": "NC-12345678",
    "formation_date": "2026-06-23"
  },
  "parent_filing_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "related_items": [
    {
      "object": "filing",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "document",
      "type": "articles_of_organization",
      "uploaded_at": "2023-11-07T05:31:56Z"
    }
  ],
  "fee": {
    "total": {
      "amount": 125,
      "currency": "USD"
    },
    "base": {
      "amount": 125,
      "currency": "USD"
    },
    "dynamic": {
      "amount": 125,
      "currency": "USD"
    },
    "late": {
      "amount": 125,
      "currency": "USD"
    },
    "credit_card": {
      "amount": 125,
      "currency": "USD"
    },
    "ach": {
      "amount": 125,
      "currency": "USD"
    },
    "items": [
      {
        "component_type": "dynamic",
        "name": "franchise_tax",
        "amount": 500,
        "currency": "USD"
      }
    ]
  },
  "status_reason": "<string>",
  "canceled_by": "<string>",
  "canceled_at": "2023-11-07T05:31:56Z",
  "cases": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "object": "case",
      "mode": "live",
      "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"
      },
      "parent_id": "fil_1a2b3c",
      "summary": "Additional information needed to complete your filing.",
      "opened_at": "2023-11-07T05:31:56Z",
      "details": "<string>",
      "request": {
        "fields": [
          {
            "name": "corrected_legal_name",
            "type": "string",
            "description": "Corrected legal name (state rejected \"Acme LLC\" — name already taken).",
            "required": true,
            "example": "Acme Holdings LLC"
          }
        ]
      },
      "response": {
        "fields": {}
      },
      "due_at": "2023-11-07T05:31:56Z",
      "resolved_at": "2023-11-07T05:31:56Z"
    }
  ]
}

Filing

Apply for an EIN

⚠️ Early access — This endpoint is in preview and may change in backwards-incompatible ways before it is marked stable. Avoid depending on it in production, and reach out before building on it.

Apply for an EIN with the IRS for a business already in your Palm account.

The business record must already have its legal name, entity type, formation jurisdiction and date, and principal address; if anything required is missing, the request is rejected with the specific fields listed.

Responsible party. Either pass a user_id for a user who already has a first name, last name, and SSN on record, or pass first_name, last_name, and ssn directly and Palm will create and link the user for you.

Result. Returns the filing in queued status, then ready_to_file → processing → filed → completed, sending a filing.* webhook at each step. The assigned EIN is on filing.result.ein_number once completed.

POST

filing

ein

Apply for an EIN

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    business_id: '987e6543-e21a-45b6-c789-012345678901',
    responsible_party: {
      user_id: '123e4567-e89b-12d3-a456-426614174000',
      first_name: 'Jane',
      last_name: 'Doe',
      ssn: '123-45-6789'
    },
    reason: 'started_new_business',
    fiscal_year_end_month: 12,
    expected_employee_count: {agricultural: 0, other: 5},
    principal_activity: {category: 'accommodations', type: 'hotel'},
    principal_activity_detail: 'Software consulting services',
    has_previous_ein: false,
    reason_detail: 'Compliance with state reporting requirements',
    wage_date: '2026-04-01',
    previous_ein: '12-3456789',
    trade_name: 'Acme Trading Co',
    form_944_election: false,
    llc_member_count: 1,
    members_are_married_couple: false,
    llc_classification: 'single_member',
    metadata: {internal_ref: 'REF-123'}
  })
};

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

import requests

url = "https://api.getpalm.com/v1/filing/ein"

payload = {
    "business_id": "987e6543-e21a-45b6-c789-012345678901",
    "responsible_party": {
        "user_id": "123e4567-e89b-12d3-a456-426614174000",
        "first_name": "Jane",
        "last_name": "Doe",
        "ssn": "123-45-6789"
    },
    "reason": "started_new_business",
    "fiscal_year_end_month": 12,
    "expected_employee_count": {
        "agricultural": 0,
        "other": 5
    },
    "principal_activity": {
        "category": "accommodations",
        "type": "hotel"
    },
    "principal_activity_detail": "Software consulting services",
    "has_previous_ein": False,
    "reason_detail": "Compliance with state reporting requirements",
    "wage_date": "2026-04-01",
    "previous_ein": "12-3456789",
    "trade_name": "Acme Trading Co",
    "form_944_election": False,
    "llc_member_count": 1,
    "members_are_married_couple": False,
    "llc_classification": "single_member",
    "metadata": { "internal_ref": "REF-123" }
}
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/filing/ein \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_id": "987e6543-e21a-45b6-c789-012345678901",
  "responsible_party": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "Jane",
    "last_name": "Doe",
    "ssn": "123-45-6789"
  },
  "reason": "started_new_business",
  "fiscal_year_end_month": 12,
  "expected_employee_count": {
    "agricultural": 0,
    "other": 5
  },
  "principal_activity": {
    "category": "accommodations",
    "type": "hotel"
  },
  "principal_activity_detail": "Software consulting services",
  "has_previous_ein": false,
  "reason_detail": "Compliance with state reporting requirements",
  "wage_date": "2026-04-01",
  "previous_ein": "12-3456789",
  "trade_name": "Acme Trading Co",
  "form_944_election": false,
  "llc_member_count": 1,
  "members_are_married_couple": false,
  "llc_classification": "single_member",
  "metadata": {
    "internal_ref": "REF-123"
  }
}
'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "filing",
  "mode": "live",
  "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"
  },
  "jurisdiction": "US-NC",
  "name": "Acme Holdings LLC",
  "expedited_tier": "same_day",
  "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "result": {
    "registration_number": "NC-12345678",
    "formation_date": "2026-06-23"
  },
  "parent_filing_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "related_items": [
    {
      "object": "filing",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "document",
      "type": "articles_of_organization",
      "uploaded_at": "2023-11-07T05:31:56Z"
    }
  ],
  "fee": {
    "total": {
      "amount": 125,
      "currency": "USD"
    },
    "base": {
      "amount": 125,
      "currency": "USD"
    },
    "dynamic": {
      "amount": 125,
      "currency": "USD"
    },
    "late": {
      "amount": 125,
      "currency": "USD"
    },
    "credit_card": {
      "amount": 125,
      "currency": "USD"
    },
    "ach": {
      "amount": 125,
      "currency": "USD"
    },
    "items": [
      {
        "component_type": "dynamic",
        "name": "franchise_tax",
        "amount": 500,
        "currency": "USD"
      }
    ]
  },
  "status_reason": "<string>",
  "canceled_by": "<string>",
  "canceled_at": "2023-11-07T05:31:56Z",
  "cases": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "object": "case",
      "mode": "live",
      "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"
      },
      "parent_id": "fil_1a2b3c",
      "summary": "Additional information needed to complete your filing.",
      "opened_at": "2023-11-07T05:31:56Z",
      "details": "<string>",
      "request": {
        "fields": [
          {
            "name": "corrected_legal_name",
            "type": "string",
            "description": "Corrected legal name (state rejected \"Acme LLC\" — name already taken).",
            "required": true,
            "example": "Acme Holdings LLC"
          }
        ]
      },
      "response": {
        "fields": {}
      },
      "due_at": "2023-11-07T05:31:56Z",
      "resolved_at": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization

string

header

required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Body

application/json

business_id

string<uuid>

required

Business ID of a business you previously vaulted with Palm.

Example:

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

responsible_party

object

required

Responsible party for the entity

Show child attributes

reason

enum<string>

required

Reason for applying

Available options:

started_new_business,

hired_employees,

banking_purposes,

changed_organization_type,

purchased_business,

created_trust,

created_pension_plan,

withholding_compliance,

other

Example:

"started_new_business"

fiscal_year_end_month

integer

required

Closing month of accounting year. 1-12, most entities use 12 for calendar year.

Required range: 1 <= x <= 12

Example:

12

expected_employee_count

object

required

Highest number of employees expected in next 12 months by category

Show child attributes

principal_activity

object

required

Principal activity category, matching the IRS online EIN flow. Pick the one that best describes the business:

accommodations: hotels, motels, casino hotels
construction: contractors and construction trades
finance: banks, brokers, lenders, investment and advisory firms
food_service: restaurants, bars, catering, coffee/ice-cream shops
health_care: physicians, dentists, hospitals, clinics, mental-health practitioners
insurance: insurance carriers, agents, and brokers
manufacturing: producing goods from raw materials
real_estate: renting, building, selling, or managing property
rental_and_leasing: renting or leasing real estate or goods
retail: selling goods to consumers (online, storefront, direct, auction)
social_assistance: nursing homes, shelters, youth services
transportation: moving cargo or passengers
warehousing: storage and warehousing
wholesale: selling goods to businesses for resale
other: anything not covered above (consulting, repair, services, etc.)

The object is discriminated by category; each category carries its own follow-up fields.

Show child attributes

principal_activity_detail

string

required

Free-text description of the principal line of merchandise sold, products produced, or services provided (IRS Form SS-4, line 17).

Example:

"Software consulting services"

has_previous_ein

boolean

required

Has the entity previously applied for and received an EIN?

Example:

false

reason_detail

string

Details for the reason. Required if reason is "other".

Example:

"Compliance with state reporting requirements"

wage_date

string<date>

Date wages will first be paid. Required if total expected employees > 0.

Example:

"2026-04-01"

previous_ein

string

Previous EIN if applicable. Required if has_previous_ein is true.

Example:

"12-3456789"

trade_name

string

Trade name / DBA if different from legal name

Example:

"Acme Trading Co"

form_944_election

boolean

Elect to file Form 944 annually instead of Form 941 quarterly. Applies if expected annual employment tax liability is $1,000 or less.

Example:

false

llc_member_count

integer

Number of members in the LLC — the IRS EIN application asks this for every LLC, so it is required when the referenced business is an LLC. When it is 2 and the business is physically located in a community property state (AZ, CA, ID, LA, NM, NV, TX, WA, WI), members_are_married_couple is required.

Required range: x >= 1

Example:

1

members_are_married_couple

boolean

Whether the two LLC members are married to each other. Required when llc_member_count is 2 and the business is physically located in a community property state (AZ, CA, ID, LA, NM, NV, TX, WA, WI), where the IRS EIN application asks whether the members are husband and wife.

Example:

false

llc_classification

enum<string>

Federal tax classification election for a married-couple LLC in a community property state (Rev. Proc. 2002-69): treat the LLC as single-member (disregarded entity) or multi-member (partnership). Required if members_are_married_couple is true.

Available options:

single_member,

multi_member

Example:

"single_member"

metadata

object

Partner-defined metadata

Example:

{ "internal_ref": "REF-123" }

Response

EIN filing created

string<uuid>

required

Unique identifier for the resource

Example:

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

object

enum<string>

required

Object type

Available options:

filing

Example:

"filing"

mode

enum<string>

required

Whether this resource was created with test or live credentials. Test and live data are fully isolated — a test resource never appears in live results and vice versa.

Available options:

test,

live

Example:

"live"

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.

Show child attributes

Example:

{
  "external_id": "user_123_in_my_system",
  "customer_tier": "premium",
  "signup_source": "mobile_app"
}

type

enum<string>

required

Filing type

Available options:

formation,

ein,

amendment,

scorp_election

status

enum<string>

required

Current status

Available options:

queued,

ready_to_file,

processing,

filed,

completed,

rejected,

canceled,

failed

entity_type

enum<string>

Entity type (for formations)

Available options:

llc,

pllc,

corporation,

pcorporation

jurisdiction

string

Jurisdiction (ISO 3166-2)

Example:

"US-NC"

name

string

Business name for the filing

Example:

"Acme Holdings LLC"

expedited_tier

string

Expedited processing tier requested for this filing, or null for standard processing. Only set on formations submitted with an expedited_tier.

Example:

"same_day"

business_id

string<uuid>

Linked business ID

result

object

Filing result — populated on completion, null until then. Shape depends on the filing type: formation → { registration_number, formation_date }; EIN → { ein_number, entity_name }. Other filing types have no result.

Option 1
Option 2

Show child attributes

parent_filing_id

string<uuid>

Parent filing ID (for bundled EIN/RA)

Bundle of obligations tracked under this formation, each with its own object type and status: filings (state registration, EIN) and the registered agent (id is the business, resolvable at GET /business/:id/registered-agent).

Option 1
Option 2

Show child attributes

documents

object[]

Documents associated with this filing

Show child attributes

fee

object | null

Fee components keyed by type (base, dynamic, late, credit_card, ach), plus a convenience total grand total (assumes credit-card payment). Only present components are included. When items is set, it lists each evaluated rule for itemized rendering — the component-keyed values are the sums across those items.

Show child attributes

status_reason

string

Reason the filing was canceled (partner request, parent off-boarded, duplicate, etc.). Only present when status is canceled.

canceled_by

string

Role that initiated the cancellation. One of: partner, palm. Only present when status is canceled.

canceled_at

string<date-time>

Timestamp the filing was canceled

cases

object[]

Cases attached to this filing. One entry per partner-visible case, in chronological order. Each case carries a typed request payload describing what Palm needs and, once submitted, a typed response. Partners respond via POST /v1/case/:case_id/response. An entry with status=needs_response is an outstanding ask — its presence is the signal that the filing needs partner action.

Show child attributes

Retrieve a case

Validate an EIN application request

⌘I

Palm Introduction

API Introduction

Endpoints

Apply for an EIN

Authorizations

Body

Response