Change the registered agent on a business

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    business_id: '987e6543-e21a-45b6-c789-012345678901',
    registered_agent: {
      type: 'person',
      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'
      },
      email: 'agent@example.com',
      phone: '919-555-1234'
    },
    metadata: {case_id: 'case_abc123'}
  })
};

fetch('https://api.getpalm.com/v1/filing/registered-agent-change', 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

Change the registered agent on a business

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

Submit a state filing to change the registered agent on file for an existing business. Pass registered_agent to change to a different provider or to the partner themselves; omit registered_agent to switch to Palm-provided RA service.

Distinct from the child registered_agent filing created during formation — this is the standalone state filing for an existing entity, FilingType.RA_CHANGE.

Business vault prerequisites. business.formation_jurisdiction must be present on the business record; the change is filed in that state. Foreign-qualified RA changes (changing the RA in a non-home state) are not yet supported.

Result. Returns the new filing in queued status. The filing then advances through ready_to_file → processing → filed → completed, firing a filing.* webhook at each step. When the filing reaches completed, the business record is updated to reflect the new RA and a registered_agent.changed webhook fires.

POST

filing

registered-agent-change

Change the registered agent on a business

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    business_id: '987e6543-e21a-45b6-c789-012345678901',
    registered_agent: {
      type: 'person',
      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'
      },
      email: 'agent@example.com',
      phone: '919-555-1234'
    },
    metadata: {case_id: 'case_abc123'}
  })
};

fetch('https://api.getpalm.com/v1/filing/registered-agent-change', 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

business_id

string<uuid>

required

Business whose registered agent is being changed. Must be a business you previously vaulted with Palm and that has business.formation_jurisdiction set.

Example:

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

registered_agent

object

required

New registered agent details. Pass partner-provided agent info to change to a different provider or to themselves; omit to switch to Palm-provided RA service.

Show child attributes

metadata

object

Optional partner-facing metadata. Stamped on the filing record.

Example:

{ "case_id": "case_abc123" }

Response

RA change 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

Form an LLC

List filings

⌘I