const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    jurisdiction: 'US-TX',
    business_id: '987e6543-e21a-45b6-c789-012345678901',
    contact: {name: 'Jane Doe', email: 'jane@acme.com', phone: '919-555-1234'},
    email: 'info@acme.com',
    principal_address: {
      street_line_1: '123 Main St',
      city: 'Raleigh',
      region: 'NC',
      postal_code: '27601',
      country: 'US',
      street_line_2: 'Suite 200',
      county: 'Mecklenburg'
    },
    phone: '512-555-1234',
    website: 'https://acme.com',
    governing_persons: [
      {
        name: {
          type: 'person',
          first: 'Jane',
          last: 'Doe',
          middle: 'A.',
          suffix: 'Jr.',
          entity_name: 'Acme Holdings LLC'
        },
        role: 'member',
        email: 'member@example.com',
        phone: '512-555-1234'
      }
    ],
    purpose: 'Any lawful purpose',
    effective_date: '2026-10-01',
    expedited_tier: 'expedited',
    metadata: {}
  })
};

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

import requests

url = "https://api.getpalm.com/v1/filing/foreign-qualification"

payload = {
    "jurisdiction": "US-TX",
    "business_id": "987e6543-e21a-45b6-c789-012345678901",
    "contact": {
        "name": "Jane Doe",
        "email": "jane@acme.com",
        "phone": "919-555-1234"
    },
    "email": "info@acme.com",
    "principal_address": {
        "street_line_1": "123 Main St",
        "city": "Raleigh",
        "region": "NC",
        "postal_code": "27601",
        "country": "US",
        "street_line_2": "Suite 200",
        "county": "Mecklenburg"
    },
    "phone": "512-555-1234",
    "website": "https://acme.com",
    "governing_persons": [
        {
            "name": {
                "type": "person",
                "first": "Jane",
                "last": "Doe",
                "middle": "A.",
                "suffix": "Jr.",
                "entity_name": "Acme Holdings LLC"
            },
            "role": "member",
            "email": "member@example.com",
            "phone": "512-555-1234"
        }
    ],
    "purpose": "Any lawful purpose",
    "effective_date": "2026-10-01",
    "expedited_tier": "expedited",
    "metadata": {}
}
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/foreign-qualification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jurisdiction": "US-TX",
  "business_id": "987e6543-e21a-45b6-c789-012345678901",
  "contact": {
    "name": "Jane Doe",
    "email": "jane@acme.com",
    "phone": "919-555-1234"
  },
  "email": "info@acme.com",
  "principal_address": {
    "street_line_1": "123 Main St",
    "city": "Raleigh",
    "region": "NC",
    "postal_code": "27601",
    "country": "US",
    "street_line_2": "Suite 200",
    "county": "Mecklenburg"
  },
  "phone": "512-555-1234",
  "website": "https://acme.com",
  "governing_persons": [
    {
      "name": {
        "type": "person",
        "first": "Jane",
        "last": "Doe",
        "middle": "A.",
        "suffix": "Jr.",
        "entity_name": "Acme Holdings LLC"
      },
      "role": "member",
      "email": "member@example.com",
      "phone": "512-555-1234"
    }
  ],
  "purpose": "Any lawful purpose",
  "effective_date": "2026-10-01",
  "expedited_tier": "expedited",
  "metadata": {}
}
'

{
  "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"
  },
  "type": "formation",
  "status": "queued",
  "entity_type": "llc",
  "jurisdiction": "US-NC",
  "legal_name": "Acme Holdings LLC",
  "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",
      "type": "formation",
      "status": "queued"
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "document",
      "types": [
        "receipt",
        "filing_confirmation"
      ],
      "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_type": "filing",
      "parent_id": "4b2d9e17-8c35-4a6b-9f02-1e7d5a3c8b96",
      "kind": "missing_information",
      "status": "needs_response",
      "summary": "Additional information needed to complete your filing.",
      "opened_at": "2023-11-07T05:31:56Z",
      "details": "<string>",
      "request": {
        "fields": [
          {
            "name": "legal_name",
            "type": "string",
            "description": "Corrected legal name (state rejected \"Acme LLC\" — name already taken).",
            "required": true,
            "example": "Acme Holdings LLC",
            "document_types": [
              "other"
            ]
          }
        ],
        "documents": [
          "906f369f-a73b-46a2-8184-ccc5c2848abd"
        ]
      },
      "response": {
        "fields": {
          "legal_name": "Acme Holdings LLC",
          "signed_consent_letter": "906f369f-a73b-46a2-8184-ccc5c2848abd"
        },
        "documents": [
          "906f369f-a73b-46a2-8184-ccc5c2848abd"
        ]
      },
      "due_at": "2023-11-07T05:31:56Z",
      "resolved_at": "2023-11-07T05:31:56Z",
      "resolution_reason": "response_received"
    }
  ]
}

Filing

Register an existing business in another state

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

Register an LLC that already exists in your Palm account to transact business in another state (a foreign qualification).

What the request carries. Reference the business with business_id and name the target state in jurisdiction. The legal name, entity type, formation jurisdiction, formation date and registration number are read from the business record and never accepted on the request. You supply only what the target state asks for beyond that: a filing contact, the principal and mailing address, governing persons where the state wants them, a registered agent if you are not using Palm’s, an expedited tier, and any state-specific fields the foreign qualification requirements endpoint lists.

What gets created. A new business record for the target-state registration, whose formation_jurisdiction is the home state and registration_jurisdiction is the target state, and a foreign_qualification filing linked to it as business_id. Owners of the referenced business are carried over. Omit registered_agent to have Palm act as registered agent in the target state; it appears under related_items.

Before anything is created the request is checked in this order: the business exists and is the formation-state registration; it carries every field the application needs (a 400 lists any gap); it is a US LLC (501 otherwise); the target state is supported (501 until a state is released); the business is not already registered there (409 already_registered, carrying the existing registration); the expedited tier is one the state offers; the legal name clears the target state’s naming rules and is available there (400 carrying the conflicts); and the payload satisfies the state’s requirements.

Result. Returns the filing in queued status. It then moves through ready_to_file → processing → filed → completed, sending a filing.* webhook at each step. Once completed, filing.result carries the target state’s registration_number and registration_date, the state documents are on the new business, and its registration number is on the new business record. Until the filing enters processing, you can cancel it with the cancel endpoint.

POST

filing

foreign-qualification

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    jurisdiction: 'US-TX',
    business_id: '987e6543-e21a-45b6-c789-012345678901',
    contact: {name: 'Jane Doe', email: 'jane@acme.com', phone: '919-555-1234'},
    email: 'info@acme.com',
    principal_address: {
      street_line_1: '123 Main St',
      city: 'Raleigh',
      region: 'NC',
      postal_code: '27601',
      country: 'US',
      street_line_2: 'Suite 200',
      county: 'Mecklenburg'
    },
    phone: '512-555-1234',
    website: 'https://acme.com',
    governing_persons: [
      {
        name: {
          type: 'person',
          first: 'Jane',
          last: 'Doe',
          middle: 'A.',
          suffix: 'Jr.',
          entity_name: 'Acme Holdings LLC'
        },
        role: 'member',
        email: 'member@example.com',
        phone: '512-555-1234'
      }
    ],
    purpose: 'Any lawful purpose',
    effective_date: '2026-10-01',
    expedited_tier: 'expedited',
    metadata: {}
  })
};

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

import requests

url = "https://api.getpalm.com/v1/filing/foreign-qualification"

payload = {
    "jurisdiction": "US-TX",
    "business_id": "987e6543-e21a-45b6-c789-012345678901",
    "contact": {
        "name": "Jane Doe",
        "email": "jane@acme.com",
        "phone": "919-555-1234"
    },
    "email": "info@acme.com",
    "principal_address": {
        "street_line_1": "123 Main St",
        "city": "Raleigh",
        "region": "NC",
        "postal_code": "27601",
        "country": "US",
        "street_line_2": "Suite 200",
        "county": "Mecklenburg"
    },
    "phone": "512-555-1234",
    "website": "https://acme.com",
    "governing_persons": [
        {
            "name": {
                "type": "person",
                "first": "Jane",
                "last": "Doe",
                "middle": "A.",
                "suffix": "Jr.",
                "entity_name": "Acme Holdings LLC"
            },
            "role": "member",
            "email": "member@example.com",
            "phone": "512-555-1234"
        }
    ],
    "purpose": "Any lawful purpose",
    "effective_date": "2026-10-01",
    "expedited_tier": "expedited",
    "metadata": {}
}
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/foreign-qualification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jurisdiction": "US-TX",
  "business_id": "987e6543-e21a-45b6-c789-012345678901",
  "contact": {
    "name": "Jane Doe",
    "email": "jane@acme.com",
    "phone": "919-555-1234"
  },
  "email": "info@acme.com",
  "principal_address": {
    "street_line_1": "123 Main St",
    "city": "Raleigh",
    "region": "NC",
    "postal_code": "27601",
    "country": "US",
    "street_line_2": "Suite 200",
    "county": "Mecklenburg"
  },
  "phone": "512-555-1234",
  "website": "https://acme.com",
  "governing_persons": [
    {
      "name": {
        "type": "person",
        "first": "Jane",
        "last": "Doe",
        "middle": "A.",
        "suffix": "Jr.",
        "entity_name": "Acme Holdings LLC"
      },
      "role": "member",
      "email": "member@example.com",
      "phone": "512-555-1234"
    }
  ],
  "purpose": "Any lawful purpose",
  "effective_date": "2026-10-01",
  "expedited_tier": "expedited",
  "metadata": {}
}
'

{
  "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"
  },
  "type": "formation",
  "status": "queued",
  "entity_type": "llc",
  "jurisdiction": "US-NC",
  "legal_name": "Acme Holdings LLC",
  "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",
      "type": "formation",
      "status": "queued"
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "document",
      "types": [
        "receipt",
        "filing_confirmation"
      ],
      "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_type": "filing",
      "parent_id": "4b2d9e17-8c35-4a6b-9f02-1e7d5a3c8b96",
      "kind": "missing_information",
      "status": "needs_response",
      "summary": "Additional information needed to complete your filing.",
      "opened_at": "2023-11-07T05:31:56Z",
      "details": "<string>",
      "request": {
        "fields": [
          {
            "name": "legal_name",
            "type": "string",
            "description": "Corrected legal name (state rejected \"Acme LLC\" — name already taken).",
            "required": true,
            "example": "Acme Holdings LLC",
            "document_types": [
              "other"
            ]
          }
        ],
        "documents": [
          "906f369f-a73b-46a2-8184-ccc5c2848abd"
        ]
      },
      "response": {
        "fields": {
          "legal_name": "Acme Holdings LLC",
          "signed_consent_letter": "906f369f-a73b-46a2-8184-ccc5c2848abd"
        },
        "documents": [
          "906f369f-a73b-46a2-8184-ccc5c2848abd"
        ]
      },
      "due_at": "2023-11-07T05:31:56Z",
      "resolved_at": "2023-11-07T05:31:56Z",
      "resolution_reason": "response_received"
    }
  ]
}

Authorizations

Authorization

string

header

required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Headers

Idempotency-Key

string

Use one key per logical submission and reuse it for every retry of that submission. A key is bound to the first request that succeeds with it and honored for 24 hours: retrying with the same key and payload returns the previously created filing with the Idempotent-Replayed: true response header instead of creating a second one. Reusing a key with a different payload or on a different operation is rejected with a 409 idempotency_key_conflict problem carrying existing_filing_id. Keys are 1-255 characters, unique per organization and mode.

Maximum string length: 255

Body

application/json

jurisdiction

string

required

The state to register in (ISO 3166-2). Becomes the registration jurisdiction of the new business record.

Example:

"US-TX"

business_id

string<uuid>

required

The existing business in your account, as registered in its formation state. Its legal name, entity type, formation jurisdiction, formation date and registration number are read from the record and are never accepted on this request.

Example:

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

contact

object

required

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

Show child attributes

string

required

Business email address

Example:

"info@acme.com"

principal_address

object

required

Principal office address, as you hold it

Show child attributes

phone

string

Business phone number

Example:

"512-555-1234"

website

string

Business website

Example:

"https://acme.com"

mailing_address

object

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

Show child attributes

governing_persons

object[]

Members or managers of the LLC, where the target state asks for them. The requirement endpoint says whether the state does.

Show child attributes

purpose

string

Purpose of the business in the target state, where the state asks for one.

Example:

"Any lawful purpose"

registered_agent

object

Your own registered agent in the target state. If omitted, Palm provides registered agent service there.

Show child attributes

effective_date

string

Delayed effective date (YYYY-MM-DD), where the state offers one. Omit to register immediately.

Example:

"2026-10-01"

expedited_tier

string

Expedited processing tier. Omit for standard processing. Valid values are jurisdiction-specific — discover them via GET /v1/filing/foreign-qualification/requirement (expedited_tiers) and price them via GET /v1/filing/foreign-qualification/fee (expedited_tiers). Rejected with 400 if the value is not offered by the jurisdiction.

Example:

"expedited"

metadata

object

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

Response

Foreign qualification 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,

foreign_qualification

status

enum<string>

required

Current status

Available options:

queued,

ready_to_file,

processing,

filed,

completed,

canceled

entity_type

enum<string>

Entity type. Set on formations and foreign qualifications (derived from the referenced business).

Available options:

llc,

professional_llc,

corporation,

professional_corporation

jurisdiction

string

Jurisdiction the filing is made in (ISO 3166-2). For a foreign qualification this is the target state.

Example:

"US-NC"

legal_name

string

Business name the filing is being made under, as sent on the request. For a foreign qualification, the legal name being registered. Changes when a legal_name_change case resolves.

Example:

"Acme Holdings LLC"

name

string

deprecated

Deprecated: use legal_name. The same value.

Example:

"Acme Holdings LLC"

expedited_tier

string

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

Example:

"same_day"

business_id

string<uuid>

Linked business ID. For a foreign qualification this is the new business record created for the target-state registration, whose formation_jurisdiction and registration_jurisdiction say where the entity was formed and where it is registered.

result

object

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

Option 1
Option 2
Option 3

Show child attributes

parent_filing_id

string<uuid>

Parent filing ID (for bundled EIN/RA)

Bundle of obligations tracked under this filing, 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

Palm Introduction

API Introduction

Endpoints

Register an existing business in another state

Authorizations

Headers

Body

Response