Form a corporation

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    jurisdiction: 'US-DE',
    entity_name: 'Acme Corp Inc.',
    purpose: 'Any lawful purpose',
    email: 'info@acme.com',
    contact: {name: 'Jane Doe', email: 'jane@acme.com', phone: '919-555-1234'},
    principal_address: {
      street_line_1: '123 Main St',
      city: 'Raleigh',
      region: 'NC',
      postal_code: '27601',
      country: 'US',
      street_line_2: 'Suite 200',
      county: 'Mecklenburg'
    },
    incorporators: [
      {
        name: {
          type: 'person',
          first: 'Jane',
          last: 'Doe',
          middle: 'A.',
          suffix: 'Jr.',
          entity_name: 'Acme Holdings LLC'
        },
        address: {
          street_line_1: '123 Main St',
          city: 'Raleigh',
          region: 'NC',
          postal_code: '27601',
          country: 'US',
          street_line_2: 'Suite 200',
          county: 'Mecklenburg'
        },
        title: 'Authorized Person',
        email: 'incorporator@example.com',
        phone: '919-555-1234'
      }
    ],
    stock_structure: {
      total_authorized_shares: 10000,
      has_par_value: true,
      par_value_per_share: 0.01,
      total_consideration: 100,
      rights_and_restrictions: 'Common stock with one vote per share.',
      classes: [
        {
          class_name: 'Common',
          authorized_shares: 10000,
          issued_shares: 1000,
          par_value_per_share: 0.01,
          consideration: 100,
          rights_and_restrictions: 'One vote per share. Dividends payable at the discretion of the board.'
        }
      ]
    },
    phone: '919-555-1234',
    website: 'https://acme.com',
    effective_date: '2026-05-01',
    initial_directors: [
      {
        name: {first: 'Jane', last: 'Doe', middle: 'A.', suffix: 'Jr.'},
        title: 'President',
        email: 'director@example.com',
        phone: '919-555-1234'
      }
    ],
    metadata: {}
  })
};

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "filing",
  "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",
  "business_id": {},
  "result": {},
  "parent_filing_id": {},
  "related_filings": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "filing"
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "document",
      "type": "articles_of_organization",
      "url": "<string>",
      "uploaded_at": "2023-11-07T05:31:56Z"
    }
  ],
  "fee": {},
  "status_reason": "<string>",
  "canceled_by": "<string>",
  "canceled_at": "2023-11-07T05:31:56Z",
  "cases": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "object": "case",
      "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": {},
      "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": {},
      "resolved_at": {}
    }
  ]
}

Filing

Form a corporation

⚠️ 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.

Form a new corporation by submitting a formation filing to the state.

What gets created. A filing record for the formation, plus a new business record in your Palm account populated with the legal name, entity type, jurisdiction, and principal address. Each person in incorporators and initial_directors is also created as a user and linked to the business as an owner.

Stock structure. Pass stock_structure to declare authorized shares and par value (required by most jurisdictions). Some states price the filing on share count or par value — preview the cost with GET /v1/filing/formation/fee before submitting.

Bundled add-ons. Pass registered_agent to specify your own RA; omit it to have Palm provision one (creates a child registered_agent filing). Pass ein to bundle an EIN application (creates a child ein filing tied to the formation).

Jurisdiction-specific fields. Some states require extra fields. Pass them as additional top-level properties — call GET /v1/filing/formation/requirement to discover what a given jurisdiction expects.

Result. Returns the new formation filing in queued status. The filing then advances through ready_to_file → processing → filed → completed, firing a filing.* webhook at each step. The state-issued registration number is available on filing.result.registration_number once the filing is completed. Child filings (RA, EIN) appear on related_filings and progress independently.

POST

filing

formation

corporation

Form a corporation

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    jurisdiction: 'US-DE',
    entity_name: 'Acme Corp Inc.',
    purpose: 'Any lawful purpose',
    email: 'info@acme.com',
    contact: {name: 'Jane Doe', email: 'jane@acme.com', phone: '919-555-1234'},
    principal_address: {
      street_line_1: '123 Main St',
      city: 'Raleigh',
      region: 'NC',
      postal_code: '27601',
      country: 'US',
      street_line_2: 'Suite 200',
      county: 'Mecklenburg'
    },
    incorporators: [
      {
        name: {
          type: 'person',
          first: 'Jane',
          last: 'Doe',
          middle: 'A.',
          suffix: 'Jr.',
          entity_name: 'Acme Holdings LLC'
        },
        address: {
          street_line_1: '123 Main St',
          city: 'Raleigh',
          region: 'NC',
          postal_code: '27601',
          country: 'US',
          street_line_2: 'Suite 200',
          county: 'Mecklenburg'
        },
        title: 'Authorized Person',
        email: 'incorporator@example.com',
        phone: '919-555-1234'
      }
    ],
    stock_structure: {
      total_authorized_shares: 10000,
      has_par_value: true,
      par_value_per_share: 0.01,
      total_consideration: 100,
      rights_and_restrictions: 'Common stock with one vote per share.',
      classes: [
        {
          class_name: 'Common',
          authorized_shares: 10000,
          issued_shares: 1000,
          par_value_per_share: 0.01,
          consideration: 100,
          rights_and_restrictions: 'One vote per share. Dividends payable at the discretion of the board.'
        }
      ]
    },
    phone: '919-555-1234',
    website: 'https://acme.com',
    effective_date: '2026-05-01',
    initial_directors: [
      {
        name: {first: 'Jane', last: 'Doe', middle: 'A.', suffix: 'Jr.'},
        title: 'President',
        email: 'director@example.com',
        phone: '919-555-1234'
      }
    ],
    metadata: {}
  })
};

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "filing",
  "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",
  "business_id": {},
  "result": {},
  "parent_filing_id": {},
  "related_filings": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "filing"
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "document",
      "type": "articles_of_organization",
      "url": "<string>",
      "uploaded_at": "2023-11-07T05:31:56Z"
    }
  ],
  "fee": {},
  "status_reason": "<string>",
  "canceled_by": "<string>",
  "canceled_at": "2023-11-07T05:31:56Z",
  "cases": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "object": "case",
      "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": {},
      "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": {},
      "resolved_at": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Body

application/json

jurisdiction

string

required

Jurisdiction (ISO 3166-2)

Example:

"US-DE"

entity_name

string

required

Legal name of the corporation being formed

Example:

"Acme Corp Inc."

purpose

string

required

Purpose clause for the articles of incorporation. Some states require user-supplied text; others (notably Delaware) use a statutory boilerplate clause that Palm fills in automatically. Distinct from the EIN principal_activity / principal_activity_detail fields, which describe the business's actual activity for IRS purposes.

Example:

"Any lawful purpose"

string

required

Business email address

Example:

"info@acme.com"

contact

object

required

Primary contact for questions about this filing. Used by Palm operations; never sent on the filing itself.

Show child attributes

principal_address

object

required

Principal office address

Show child attributes

incorporators

object[]

required

Persons or entities executing the articles of incorporation (incorporators). At least one required.

Show child attributes

stock_structure

object

required

Authorized capital stock structure

Show child attributes

phone

string

Business phone number

Example:

"919-555-1234"

website

string

Business website

Example:

"https://acme.com"

effective_date

string

Delayed effective date (YYYY-MM-DD). If omitted, defaults to the date the formation request is received by Palm.

Example:

"2026-05-01"

mailing_address

object

Mailing address if different from the principal office. Defaults to principal_address when omitted.

Show child attributes

initial_directors

object[]

Initial board of directors and/or corporate officers. Optional on most state formation forms but useful for downstream records.

Show child attributes

registered_agent

object

Registered agent. If provided, the partner's RA is used on the filing. If omitted, Palm provides registered agent service.

Show child attributes

ein

object

Bundle an EIN application with the formation. Palm submits to IRS after the formation succeeds.

Show child attributes

metadata

object

Partner-defined metadata. Round-tripped on webhooks and the filing record.

Response

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

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,

registered_agent,

ra_change,

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,

corporation

jurisdiction

object

Jurisdiction (ISO 3166-2)

Example:

"US-NC"

name

object

Business name for the filing

Example:

"Acme Holdings LLC"

business_id

object

Linked business ID

result

object

Filing result — populated on completion. Contents vary by filing type. Formation: { registration_number, formation_date }. EIN: { ein_number, entity_name }.

parent_filing_id

object

Parent filing ID (for bundled EIN/RA)

Related filings (EIN, registered agent)

Show child attributes

documents

object[]

Documents associated with this filing

Show child attributes

fee

object

Fee components keyed by type (base, dynamic, late, credit_card, ach). 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.

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

Apply for an EIN

Form an LLC

⌘I