> ## Documentation Index > Fetch the complete documentation index at: https://docs.getpalm.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](mailto:support@getpalm.com) 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`. ## OpenAPI ````yaml /api-reference/v1/openapi.json post /v1/filing/ein openapi: 3.0.0 info: title: Palm Partner API description: >- The Palm API is identity verification and compliance infrastructure for US businesses: onboard businesses, verify businesses and people (KYB/KYC) against authoritative sources, monitor them for changes in real time, and act on their behalf through filings, formation, and registered agent services. version: '1.0' contact: name: Palm Support url: https://getpalm.com email: support@getpalm.com termsOfService: https://getpalm.com/terms license: name: Proprietary url: https://getpalm.com/license servers: - url: https://api.getpalm.com description: Production security: [] tags: - name: Registry description: Search business registries - name: Business description: Manage the businesses in your portfolio - name: User description: Manage the people in your portfolio - name: Verification description: Identity and business verification - name: Monitor description: Continuous monitoring of businesses paths: /v1/filing/ein: post: tags: - Filing summary: Apply for an EIN description: >- > **⚠️ 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](mailto:support@getpalm.com) 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`. operationId: applyForEin parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EinApplicationRequest' responses: '201': description: EIN filing created content: application/json: schema: $ref: '#/components/schemas/Filing' '400': description: >- Missing required fields on the business record, or invalid request data '404': description: Business not found security: - ApiKey: [] components: schemas: EinApplicationRequest: type: object properties: business_id: type: string description: >- Business ID of a business you previously [vaulted](/api-reference/v1/business/add-a-business) with Palm. format: uuid example: 987e6543-e21a-45b6-c789-012345678901 responsible_party: description: Responsible party for the entity allOf: - $ref: '#/components/schemas/EinResponsibleParty' reason: type: string description: Reason for applying enum: - started_new_business - hired_employees - banking_purposes - changed_organization_type - purchased_business - created_trust - created_pension_plan - withholding_compliance - other example: started_new_business reason_detail: type: string description: Details for the reason. Required if reason is "other". example: Compliance with state reporting requirements fiscal_year_end_month: type: integer minimum: 1 maximum: 12 description: >- Closing month of accounting year. 1-12, most entities use 12 for calendar year. example: 12 expected_employee_count: description: Highest number of employees expected in next 12 months by category allOf: - $ref: '#/components/schemas/EinExpectedEmployeeCount' wage_date: type: string format: date description: >- Date wages will first be paid. Required if total expected employees > 0. example: '2026-04-01' principal_activity: description: >- 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. oneOf: - $ref: '#/components/schemas/AccommodationsActivity' - $ref: '#/components/schemas/ConstructionActivity' - $ref: '#/components/schemas/FinanceActivity' - $ref: '#/components/schemas/FoodServiceActivity' - $ref: '#/components/schemas/HealthCareActivity' - $ref: '#/components/schemas/InsuranceActivity' - $ref: '#/components/schemas/ManufacturingActivity' - $ref: '#/components/schemas/RealEstateActivity' - $ref: '#/components/schemas/RentalAndLeasingActivity' - $ref: '#/components/schemas/RetailActivity' - $ref: '#/components/schemas/SocialAssistanceActivity' - $ref: '#/components/schemas/TransportationActivity' - $ref: '#/components/schemas/WarehousingActivity' - $ref: '#/components/schemas/WholesaleActivity' - $ref: '#/components/schemas/OtherActivity' discriminator: propertyName: category mapping: accommodations: $ref: '#/components/schemas/AccommodationsActivity' construction: $ref: '#/components/schemas/ConstructionActivity' finance: $ref: '#/components/schemas/FinanceActivity' food_service: $ref: '#/components/schemas/FoodServiceActivity' health_care: $ref: '#/components/schemas/HealthCareActivity' insurance: $ref: '#/components/schemas/InsuranceActivity' manufacturing: $ref: '#/components/schemas/ManufacturingActivity' real_estate: $ref: '#/components/schemas/RealEstateActivity' rental_and_leasing: $ref: '#/components/schemas/RentalAndLeasingActivity' retail: $ref: '#/components/schemas/RetailActivity' social_assistance: $ref: '#/components/schemas/SocialAssistanceActivity' transportation: $ref: '#/components/schemas/TransportationActivity' warehousing: $ref: '#/components/schemas/WarehousingActivity' wholesale: $ref: '#/components/schemas/WholesaleActivity' other: $ref: '#/components/schemas/OtherActivity' principal_activity_detail: type: string description: >- 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: type: boolean description: Has the entity previously applied for and received an EIN? example: false previous_ein: type: string description: Previous EIN if applicable. Required if has_previous_ein is true. example: 12-3456789 trade_name: type: string description: Trade name / DBA if different from legal name example: Acme Trading Co form_944_election: type: boolean description: >- 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: type: integer minimum: 1 description: >- 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. example: 1 members_are_married_couple: type: boolean description: >- 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: type: string description: >- 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. enum: - single_member - multi_member example: single_member metadata: type: object description: Partner-defined metadata example: internal_ref: REF-123 required: - business_id - responsible_party - reason - fiscal_year_end_month - expected_employee_count - principal_activity - principal_activity_detail - has_previous_ein Filing: type: object properties: id: type: string description: Unique identifier for the resource format: uuid example: 123e4567-e89b-12d3-a456-426614174000 object: type: string description: Object type example: filing enum: - filing mode: type: string description: >- 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. enum: - test - live example: live created_at: type: string description: ISO 8601 timestamp of when the resource was created format: date-time example: '2025-10-24T10:30:00Z' updated_at: type: string description: ISO 8601 timestamp of when the resource was last updated format: date-time example: '2025-10-24T15:45:00Z' metadata: type: object description: >- 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. additionalProperties: type: string example: external_id: user_123_in_my_system customer_tier: premium signup_source: mobile_app type: type: string description: Filing type enum: - formation - ein - amendment - scorp_election status: type: string description: Current status enum: - queued - ready_to_file - processing - filed - completed - rejected - canceled - failed entity_type: type: string description: Entity type (for formations) enum: - llc - pllc - corporation - pcorporation jurisdiction: type: string description: Jurisdiction (ISO 3166-2) example: US-NC name: type: string description: Business name for the filing example: Acme Holdings LLC expedited_tier: type: string description: >- 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: type: string description: Linked business ID format: uuid result: description: >- 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. oneOf: - $ref: '#/components/schemas/FormationFilingResult' - $ref: '#/components/schemas/EinFilingResult' nullable: true parent_filing_id: type: string description: Parent filing ID (for bundled EIN/RA) format: uuid related_items: type: array description: >- 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`). items: oneOf: - $ref: '#/components/schemas/FilingRelatedItem' - $ref: '#/components/schemas/RegisteredAgentRelatedItem' documents: description: Documents associated with this filing type: array items: $ref: '#/components/schemas/FilingDocument' fee: description: >- 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. nullable: true type: object allOf: - $ref: '#/components/schemas/FeeBreakdown' status_reason: type: string description: >- Reason the filing was canceled (partner request, parent off-boarded, duplicate, etc.). Only present when status is `canceled`. canceled_by: type: string description: >- Role that initiated the cancellation. One of: `partner`, `palm`. Only present when status is `canceled`. canceled_at: type: string description: Timestamp the filing was canceled format: date-time cases: description: >- 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. type: array items: $ref: '#/components/schemas/Case' required: - id - object - mode - created_at - updated_at - metadata - type - status EinResponsibleParty: type: object properties: user_id: type: string description: >- Existing user ID to reference as the responsible party. If provided, first_name, last_name, and ssn are not required in the request but must be present in the user vault. format: uuid example: 123e4567-e89b-12d3-a456-426614174000 first_name: type: string description: First name. Required if user_id is not provided. example: Jane last_name: type: string description: Last name. Required if user_id is not provided. example: Doe ssn: type: string description: SSN or ITIN. Required if user_id is not provided. example: 123-45-6789 EinExpectedEmployeeCount: type: object properties: agricultural: type: integer minimum: 0 description: Expected agricultural employees in next 12 months example: 0 other: type: integer minimum: 0 description: Expected other (non-agricultural) employees in next 12 months example: 5 required: - agricultural - other AccommodationsActivity: type: object properties: category: type: string enum: - accommodations example: accommodations type: type: string description: Type of accommodation enum: - casino_hotel - hotel - motel - other example: hotel required: - category - type ConstructionActivity: type: object properties: category: type: string enum: - construction example: construction detail: description: Construction follow-up details allOf: - $ref: '#/components/schemas/ConstructionDetail' required: - category - detail FinanceActivity: type: object properties: category: type: string enum: - finance example: finance type: type: string description: Type of finance activity enum: - commodities_broker - credit_card_issuing - investment_advice - investment_club - investment_holding - mortgage_broker - mortgage_company - portfolio_management - sales_financing - securities_broker - trust_administration - venture_capital - other example: investment_advice required: - category - type FoodServiceActivity: type: object properties: category: type: string enum: - food_service example: food_service type: type: string description: Type of food service enum: - bar - bar_and_restaurant - catering_service - coffee_shop - fast_food_restaurant - full_service_restaurant - ice_cream_shop - mobile_food_service - other example: full_service_restaurant required: - category - type HealthCareActivity: type: object properties: category: type: string enum: - health_care example: health_care includes_md: type: boolean description: Does the establishment include M.D. practitioners? example: true md_role: type: string description: M.D. practitioner role. Required when includes_md is true. enum: - medical_doctor - psychiatrist - other_mental_health_practitioner non_md_role: type: string description: Non-M.D. practitioner type. Required when includes_md is false. enum: - chiropractor - dentist - hmo_medical_center - hospital - kidney_dialysis_center - optometrist - outpatient_care_center - podiatrist - psychologist - other_mental_health_practitioner - other required: - category - includes_md InsuranceActivity: type: object properties: category: type: string enum: - insurance example: insurance type: type: string description: Type of insurance activity enum: - insurance_carrier - insurance_agent_or_broker - other example: insurance_agent_or_broker support_activity_detail: type: string description: Description of the support activity. Required when type is other. example: Claims adjusting required: - category - type ManufacturingActivity: type: object properties: category: type: string enum: - manufacturing example: manufacturing goods: type: string description: Type of goods produced and primary materials used example: Aluminum cans from sheet aluminum required: - category - goods RealEstateActivity: type: object properties: category: type: string enum: - real_estate example: real_estate type: type: string description: Type of real-estate activity enum: - rent_lease_owned_property - use_capital_to_build_property - sell_property_for_others - manage_real_estate_for_others - other example: rent_lease_owned_property rental_property_type: type: string description: >- Property type rented/leased. Required when type is rent_lease_owned_property. enum: - residential - commercial_industrial - other construction: description: >- Construction details. Required when type is use_capital_to_build_property (the IRS routes this path through the construction questions). allOf: - $ref: '#/components/schemas/ConstructionDetail' required: - category - type RentalAndLeasingActivity: type: object properties: category: type: string enum: - rental_and_leasing example: rental_and_leasing type: type: string description: Type of rental/leasing activity enum: - rent_lease_sell_real_estate - rent_or_lease_goods - manage_real_estate_for_others example: rent_or_lease_goods real_estate_activity: type: string description: >- Real-estate activity. Required when type is rent_lease_sell_real_estate. enum: - real_estate_agent - rent_residential - rent_commercial_industrial goods: type: string description: >- Type of goods rented or leased. Required when type is rent_or_lease_goods. example: Construction equipment required: - category - type RetailActivity: type: object properties: category: type: string enum: - retail example: retail type: type: string description: Type of retail activity enum: - selling_goods_online - storefront_sales - direct_sales - auction_house - other example: storefront_sales direct_sales_method: type: string description: Direct-sales method. Required when type is direct_sales. enum: - catalogue - mail_order - door_to_door required: - category - type SocialAssistanceActivity: type: object properties: category: type: string enum: - social_assistance example: social_assistance type: type: string description: Type of social-assistance activity enum: - nursing_home - shelter - youth_services - other example: youth_services required: - category - type TransportationActivity: type: object properties: category: type: string enum: - transportation example: transportation type: type: string description: What the business primarily transports enum: - cargo - passengers - support_activity example: cargo cargo_mode: type: string description: Cargo transport mode. Required when type is cargo. enum: - air - rail - trucking - water - other passenger_mode: type: string description: Passenger transport mode. Required when type is passengers. enum: - limousine - shuttle_bus - taxi - other required: - category - type WarehousingActivity: type: object properties: category: type: string enum: - warehousing example: warehousing required: - category WholesaleActivity: type: object properties: category: type: string enum: - wholesale example: wholesale owns_goods: type: boolean description: Does the business own or take title to the goods? example: true receives_commission: type: boolean description: Does the business receive a commission or fee? example: false goods: type: string description: Type of goods sold example: Industrial cleaning supplies required: - category - owns_goods - receives_commission - goods OtherActivity: type: object properties: category: type: string enum: - other example: other type: type: string description: Type of activity enum: - consulting - manufacturing - organization - rental - repair - sell_goods - service - other example: consulting required: - category - type FormationFilingResult: type: object properties: registration_number: type: string nullable: true description: State-assigned registration/file number. example: NC-12345678 formation_date: type: string format: date nullable: true description: Date the entity was formed (YYYY-MM-DD). example: '2026-06-23' required: - registration_number - formation_date EinFilingResult: type: object properties: ein_number: type: string nullable: true description: Issued Employer Identification Number. example: 12-3456789 entity_name: type: string nullable: true description: Legal entity name the EIN was issued to. example: Acme Holdings LLC required: - ein_number - entity_name FilingRelatedItem: type: object properties: object: type: string description: Object type enum: - filing id: type: string description: Filing ID format: uuid type: type: string description: Filing type enum: - formation - ein - amendment - scorp_election status: type: string description: Current filing status enum: - queued - ready_to_file - processing - filed - completed - rejected - canceled - failed required: - object - id - type - status RegisteredAgentRelatedItem: type: object properties: object: type: string description: Object type enum: - registered_agent id: type: string description: Business ID that owns the registered-agent resource format: uuid status: type: string description: Current registered-agent status enum: - pending - active - termination_requested - terminated - failed required: - object - id - status FilingDocument: type: object properties: id: type: string description: Document ID format: uuid object: type: string description: Object type enum: - document type: type: string description: Document type example: articles_of_organization uploaded_at: type: string description: Upload timestamp format: date-time required: - id - object - type - uploaded_at FeeBreakdown: type: object properties: base: description: Base filing fee total. allOf: - $ref: '#/components/schemas/FeeAmount' dynamic: description: >- Variable fee total (e.g. franchise tax, share-based or expedited surcharges). allOf: - $ref: '#/components/schemas/FeeAmount' late: description: Late fee total. allOf: - $ref: '#/components/schemas/FeeAmount' credit_card: description: Credit-card payment surcharge total. allOf: - $ref: '#/components/schemas/FeeAmount' ach: description: ACH payment surcharge total. allOf: - $ref: '#/components/schemas/FeeAmount' total: description: >- Grand total across the applicable fee components — a convenience so you do not have to sum the breakdown yourself. Assumes a credit-card payment method, so it is `base + dynamic + late + credit_card` (the mutually-exclusive `ach` surcharge is excluded). `items` and any `expedited_tiers` menu are not included; a requested `expedited_tier` surcharge is already in `dynamic`. Always an estimate. allOf: - $ref: '#/components/schemas/FeeAmount' items: description: >- Itemized breakdown — one entry per evaluated rule. Component totals above are sums across these. type: array items: $ref: '#/components/schemas/FeeLine' required: - total Case: type: object properties: id: type: string description: Unique identifier for the resource format: uuid example: 123e4567-e89b-12d3-a456-426614174000 object: type: string description: Object type example: case enum: - case mode: type: string description: >- 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. enum: - test - live example: live created_at: type: string description: ISO 8601 timestamp of when the resource was created format: date-time example: '2025-10-24T10:30:00Z' updated_at: type: string description: ISO 8601 timestamp of when the resource was last updated format: date-time example: '2025-10-24T15:45:00Z' metadata: type: object description: >- 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. additionalProperties: type: string example: external_id: user_123_in_my_system customer_tier: premium signup_source: mobile_app parent_type: type: string description: Type of the parent resource this case attaches to. enum: - filing - verification - business - session parent_id: type: string description: ID of the parent resource (filing_id, verification_id, etc.). example: fil_1a2b3c kind: type: string description: >- Typed kind of case. Each kind has its own request/response payload shape — see the request/response fields. enum: - missing_information - ra_termination status: type: string description: >- Lifecycle status. `needs_response` means the partner must act; `under_review` means Palm is working on it. Both are open states. `resolved` and `superseded` are terminal. enum: - needs_response - under_review - resolved - superseded summary: type: string description: One-line summary of the case. example: Additional information needed to complete your filing. details: type: string description: Markdown-formatted details about the case. request: description: >- Typed request payload — what Palm is asking for. Shape varies by kind. allOf: - $ref: '#/components/schemas/CaseRequestPayload' response: description: >- Typed response payload — what the partner submitted. Present once the partner has responded. Shape varies by kind. allOf: - $ref: '#/components/schemas/CaseResponsePayload' due_at: type: string description: Timestamp by which the case is expected to be resolved. format: date-time opened_at: type: string description: Timestamp the case was opened. format: date-time resolved_at: type: string description: Timestamp the case was resolved or superseded. format: date-time resolution_reason: type: string description: >- Why the case left an open state. Set when status is `resolved` or `superseded`. enum: - response_received - no_response_needed - parent_canceled - parent_completed - parent_failed required: - id - object - mode - created_at - updated_at - metadata - parent_type - parent_id - kind - status - summary - opened_at ConstructionDetail: type: object properties: single_trade: type: boolean description: Does the business focus on a single construction trade? example: true trade: type: string description: The single construction trade. Required when single_trade is true. example: Electrical construction_type: type: string description: Type of construction. Required when single_trade is false. enum: - new_residential - remodeling_residential - non_residential - other_structures construction_type_detail: type: string description: >- Description of the structures built. Required when construction_type is other_structures. example: Bridges and tunnels required: - single_trade FeeAmount: type: object properties: amount: type: number description: Fee amount in whole units example: 125 currency: type: string description: Currency code example: USD required: - amount - currency FeeLine: type: object properties: component_type: type: string description: Component type this rule rolls up under enum: - base - dynamic - late - credit_card - ach example: dynamic name: type: string description: >- Stable identifier within the component (e.g., "filing", "franchise_tax", "expedited"). "default" when there is exactly one rule for this component. example: franchise_tax amount: type: number description: Fee amount in whole units example: 500 currency: type: string description: Currency code example: USD required: - component_type - name - amount - currency CaseRequestPayload: type: object properties: fields: description: 'Fields you''re being asked to supply (kind: missing_information).' type: array items: $ref: '#/components/schemas/FieldSpec' CaseResponsePayload: type: object properties: fields: type: object description: 'Map of field name to value (kind: missing_information).' additionalProperties: true FieldSpec: type: object properties: name: type: string description: >- Stable machine-readable identifier for the requested field. Used as the key in the response payload. example: corrected_legal_name type: type: string description: >- Primitive type of the requested value. One of: string, number, boolean, date. example: string description: type: string description: Human-readable prompt explaining what is being asked. example: >- Corrected legal name (state rejected "Acme LLC" — name already taken). required: type: boolean description: >- Whether this field must be present in the response. Defaults to true. example: true example: description: Example value to help you understand the expected format. oneOf: - type: string - type: number - type: boolean example: Acme Holdings LLC required: - name - type - description securitySchemes: ApiKey: scheme: bearer bearerFormat: opaque type: http description: 'Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx' ````