# Introduction Source: https://docs.getpalm.com/api-reference/introduction Base URL and versioning for the Palm API. The Palm API gives you programmatic access to business and person verification, continuous monitoring, and compliance filings — formations, EINs, registered agent, and annual reports. Authentication How to authenticate requests to the Palm API. [Open](/get-started/authentication) Get access Request API keys and start building with Palm. [Open](/get-started/get-access) ## Base URL All API requests are made to: ```text theme={null} https://api.getpalm.com/v1 ``` ## Versioning The Palm API uses URL-based versioning to ensure stability and backward compatibility. Version numbers are included in the URL path: ```text theme={null} https://api.getpalm.com/v1/business/registry/search ``` ### Version strategy * **Current version**: `v1` * **Version format**: Major versions only (v1, v2, etc.) * **Version location**: First path segment after the base URL ### Version lifecycle * New versions are released for breaking changes only * Previous versions remain supported for at least 12 months after a new version is released * Deprecation notices are sent via email and shown in API responses 3 months before sunset ## Support Need help? Contact our support team at [support@getpalm.com](mailto:support@getpalm.com). ## Next steps Test mode Build and validate your integration in an isolated sandbox. [Open](/get-started/test-mode) Webhooks overview Receive real-time notifications when events occur across Verify, Monitor, and Comply. [Open](/developer-guide/webhooks) # Add a business Source: https://docs.getpalm.com/api-reference/v1/business/add-a-business /api-reference/v1/openapi.json post /v1/business Add one of your businesses, customers or applicants to Palm. This is a common first step when integrating with Palm. Provide optional display name, metadata, and vault data. Vault fields use the `business.*` key format (e.g., `business.legal_name`, `business.ein`). If you plan to file an EIN application, include the required vault fields: legal_name, entity_type, formation_jurisdiction, formation_date, address_line_1, city, region, and postal_code. # Delete a business Source: https://docs.getpalm.com/api-reference/v1/business/delete-a-business /api-reference/v1/openapi.json delete /v1/business/{business_id} Deletes a business and its associated data including vault data and owner relationships. This performs a soft delete by default, setting the business status to deleted. # Delete a document Source: https://docs.getpalm.com/api-reference/v1/business/delete-a-document /api-reference/v1/openapi.json delete /v1/business/{business_id}/document/{document_id} Removes a document from this business. The file is permanently deleted from storage and cannot be recovered. To retrieve a document's details before deleting it, use the [document endpoint](/api-reference/v1/documents/retrieve-document-metadata). # List documents Source: https://docs.getpalm.com/api-reference/v1/business/list-documents /api-reference/v1/openapi.json get /v1/business/{business_id}/document Returns all documents uploaded for this business, including each document's types, filename, size, content type, and status. Filter by document `type` (matches any entry of `types`), `status`, or the work a document is part of (`case_id`, `filing_id`). Use a document `id` with the [document endpoint](/api-reference/v1/documents/retrieve-document-metadata) to retrieve its details, or the [download endpoint](/api-reference/v1/documents/download-a-document) to download the file. # Retrieve a business Source: https://docs.getpalm.com/api-reference/v1/business/retrieve-a-business /api-reference/v1/openapi.json get /v1/business/{business_id} Retrieves a business by ID. Returns the business record with status, display name, and metadata. Non-encrypted vault fields (such as address) are included in the response; encrypted fields like EIN are referenced by fingerprint only. # Search businesses Source: https://docs.getpalm.com/api-reference/v1/business/search-businesses /api-reference/v1/openapi.json post /v1/business/search Search for businesses in your organization with optional filters. Filter by legal_name (partial match), entity_type (exact match), or EIN (exact match). Returns paginated results using cursor-based pagination. # Update a business Source: https://docs.getpalm.com/api-reference/v1/business/update-a-business /api-reference/v1/openapi.json patch /v1/business/{business_id} Updates a business's display name or metadata. Metadata updates are merged with existing values; set a key to null to remove it. # Upload document Source: https://docs.getpalm.com/api-reference/v1/business/upload-document /api-reference/v1/openapi.json post /v1/business/{business_id}/document Uploads a document for this business, such as its articles of incorporation, operating agreement, or EIN letter, as multipart form data. Returns the created document, including its `id`. Use that `id` with the [document endpoint](/api-reference/v1/documents/retrieve-document-metadata) to retrieve its details, or the [download endpoint](/api-reference/v1/documents/download-a-document) to download the file. # List cases Source: https://docs.getpalm.com/api-reference/v1/case/list-cases /api-reference/v1/openapi.json get /v1/case > **⚠️ 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. List cases visible to the caller. Internal cases that have never been routed to the partner are excluded. Supports filtering by parent, status, and kind, plus cursor-based pagination. # Retrieve a case Source: https://docs.getpalm.com/api-reference/v1/case/retrieve-a-case /api-reference/v1/openapi.json get /v1/case/{case_id} > **⚠️ 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. # Submit a response to a case Source: https://docs.getpalm.com/api-reference/v1/case/submit-a-response-to-a-case /api-reference/v1/openapi.json post /v1/case/{case_id}/response > **⚠️ 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. Partner submits the payload the case requires. Only allowed when `status=needs_response`. Documents are uploaded to the business first and referenced by id, either as the value of a `document` field or in `documents`; a successful submit relates each one to the case and its filing, transitions status to `under_review`, and fires `case.updated`. # Get a document request Source: https://docs.getpalm.com/api-reference/v1/document-request/get-a-document-request /api-reference/v1/openapi.json get /v1/document-request/{document_request_id} > **⚠️ 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. Retrieve a document request, including its status, result, and failure reason. # Get document request fee estimate Source: https://docs.getpalm.com/api-reference/v1/document-request/get-document-request-fee-estimate /api-reference/v1/openapi.json get /v1/document-request/fee > **⚠️ 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. Estimated government fee for a document type in one jurisdiction and entity type. Estimates are for planning: the billed government fee is what the jurisdiction actually charged at fulfillment. Omit `expedited_tier` and, where the state offers expedited processing, the response includes `expedited_tiers`: a menu of `{ tier, fee }` where `fee` is the added surcharge as an `{ amount, currency }` pair (total cost = the standard fee components + `fee.amount`). Supply `expedited_tier` and the surcharge is priced into `fee`; a tier the state does not offer returns `400`. # List document requests Source: https://docs.getpalm.com/api-reference/v1/document-request/list-document-requests /api-reference/v1/openapi.json get /v1/document-request > **⚠️ 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. List document requests, newest first. # Request a document Source: https://docs.getpalm.com/api-reference/v1/document-request/request-a-document /api-reference/v1/openapi.json post /v1/document-request > **⚠️ 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. Request an official document for a registration, identified by exactly one of `palm_id`, `registration_jurisdiction` with `registration_number`, or `business_id`. The request is accepted immediately and fulfilled asynchronously: poll it, or subscribe to the `document_request.processing`, `document_request.completed` and `document_request.failed` webhook events. A business is added to your portfolio for the registration when none exists yet. Unsupported jurisdictions and entity types are refused at creation. In test mode no state order is placed: the request moves through `processing` and completes with a sample certificate, or fails as directed by `metadata._simulate`. # Download a document Source: https://docs.getpalm.com/api-reference/v1/documents/download-a-document /api-reference/v1/openapi.json get /v1/document/{document_id}/content Downloads a document by its `id`. The response is the raw file, served with the document's `Content-Type` and a `Content-Disposition: attachment` header so it saves with its original filename. A document can be downloaded as often as you need, for as long as it exists. # Retrieve document metadata Source: https://docs.getpalm.com/api-reference/v1/documents/retrieve-document-metadata /api-reference/v1/openapi.json get /v1/document/{document_id} Returns a document by its `id`, including its type, filename, size, content type, and status. You can find a document `id` in the `documents` array of a filing or business response. To download the file itself, use the [download endpoint](/api-reference/v1/documents/download-a-document). To list or upload documents for a specific business, use the [business document endpoints](/api-reference/v1/business/list-documents). # Apply for an EIN Source: https://docs.getpalm.com/api-reference/v1/filing/apply-for-an-ein /api-reference/v1/openapi.json post /v1/filing/ein 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`. Until the filing enters `processing`, you can cancel it with the [cancel endpoint](/api-reference/v1/filing/cancel-a-filing). # Cancel a filing Source: https://docs.getpalm.com/api-reference/v1/filing/cancel-a-filing /api-reference/v1/openapi.json post /v1/filing/{filing_id}/cancellation > **⚠️ 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. Cancel a filing before processing begins. **When it succeeds.** The filing must still be in a pre-processing status (`queued` or `ready_to_file`). It moves to the terminal `canceled` status, a `filing.canceled` webhook fires, and the response returns the filing with `canceled_at` and `status_reason` set. **When it fails.** Once the filing has entered `processing` (or finished), cancellation returns a 409 `filing_not_cancellable` problem whose `current_status` member carries the filing status the decision was made against. There is no dry-run check — call cancel and read the response. A rejected attempt on an in-progress filing is still surfaced to the operations team working it, so they know you asked before anything is finalized with the state. **Related filings.** Each filing is evaluated on its own status. Canceling a formation that is still pre-processing also cancels its pre-processing related filings (an EIN cannot exist without the entity); each canceled filing sends its own `filing.canceled` webhook. A pending Palm registered agent on the formation is canceled with it: its status moves to `canceled` and a `registered_agent.canceled` webhook fires. The reverse never applies: a related EIN filing can be canceled independently — including after its formation has completed — without touching the formation. **Fees.** Cancellation has no billing side effects. Palm fees are only charged on completion, and government fees ride on the filing that incurred them. # Form a corporation Source: https://docs.getpalm.com/api-reference/v1/filing/form-a-corporation /api-reference/v1/openapi.json post /v1/filing/formation/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](mailto:support@getpalm.com) before building on it. Form a new corporation by submitting a formation filing to the state. **What gets created.** The formation filing, plus a business record in your Palm account (legal name, entity type, jurisdiction, and principal address). Everyone you list in `incorporators`, `initial_directors`, and `initial_officers` 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 states. Some states price the filing on share count or par value — preview the cost with the [formation fee endpoint](/api-reference/v1/filing/get-formation-fee-estimate) first. **Add-ons.** Pass `registered_agent` to use your own; omit it to have Palm act as the registered agent. Pass `ein` to apply for an EIN once the formation completes. Each add-on appears under `related_items` and progresses independently — EIN as a `filing`, the Palm registered agent as a `registered_agent` (tracked at `GET /business/:id/registered-agent`). **Jurisdiction-specific fields.** Some states require extra fields. Send them as additional top-level properties — the [formation requirements endpoint](/api-reference/v1/filing/get-formation-requirements) lists what a given state expects. **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`, the state registration number is on `filing.result.registration_number`. Until the filing enters `processing`, you can cancel it with the [cancel endpoint](/api-reference/v1/filing/cancel-a-filing). # Form an LLC Source: https://docs.getpalm.com/api-reference/v1/filing/form-an-llc /api-reference/v1/openapi.json post /v1/filing/formation/llc Form a new LLC by submitting a formation filing to the state. **What gets created.** The formation filing, plus a business record in your Palm account (legal name, entity type, jurisdiction, and principal address). Everyone you list in `organizers` and `initial_governing_persons` is also created as a user and linked to the business as an owner. **Add-ons.** Pass `registered_agent` to use your own; omit it to have Palm act as the registered agent. Pass `ein` to apply for an EIN once the formation completes. Each add-on appears under `related_items` and progresses independently — EIN as a `filing`, the Palm registered agent as a `registered_agent` (tracked at `GET /business/:id/registered-agent`). **Jurisdiction-specific fields.** Some states require extra fields. Send them as additional top-level properties — the [formation requirements endpoint](/api-reference/v1/filing/get-formation-requirements) lists what a given state expects. **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`, the state registration number is on `filing.result.registration_number`. Until the filing enters `processing`, you can cancel it with the [cancel endpoint](/api-reference/v1/filing/cancel-a-filing). # Get foreign qualification fee estimate Source: https://docs.getpalm.com/api-reference/v1/filing/get-foreign-qualification-fee-estimate /api-reference/v1/openapi.json get /v1/filing/foreign-qualification/fee > **⚠️ 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. Estimate the government fees for registering an existing business in a state before submitting. Fees are broken down by component (`base`, `dynamic`, `late`, `credit_card`, `ach`); only the components that apply to the jurisdiction are returned. `fee.total` is the all-in grand total assuming credit-card payment. It is always an estimate. Omit `expedited_tier` and, where the state offers expedited processing, the response includes `expedited_tiers`: a menu of `{ tier, fee }` where `fee` is the added surcharge for that speed. Pass `expedited_tier` to fold one tier’s surcharge into the components instead; a tier the state does not offer returns `400`, the same as on the create endpoint. Any other query parameter is forwarded to the fee calculation as an extra input; a `400` lists any input the state requires that was not supplied. Returns `404` where no fee data is available for the jurisdiction. # Get foreign qualification requirements Source: https://docs.getpalm.com/api-reference/v1/filing/get-foreign-qualification-requirements /api-reference/v1/openapi.json get /v1/filing/foreign-qualification/requirement > **⚠️ 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. Discover what registering an existing business in a given state needs. Call this before building a request so you know what to collect. `schema` is a JSON Schema of the request body: the common fields plus the fields the state requires. Everything Palm reads from the referenced business (legal name, entity type, formation jurisdiction, formation date, registration number) is absent, since you never supply it. `effective_date` is present only when the state offers a delayed effective date, with the state’s own description of its limits. `prerequisites` lists the documents the state needs alongside the application, each with whether it is always required and who supplies it; Palm orders the home-state certificate as part of the filing. `post_filing_obligations` lists what the registration starts once accepted. `expedited_tiers` lists the expedited processing tiers the state offers (the accepted `expedited_tier` values on create); price each one with the [foreign qualification fee endpoint](/api-reference/v1/filing/get-foreign-qualification-fee-estimate). Returns `501` for a state Palm does not yet support. # Get formation fee estimate Source: https://docs.getpalm.com/api-reference/v1/filing/get-formation-fee-estimate /api-reference/v1/openapi.json get /v1/filing/formation/fee > **⚠️ Early access (corporations)** — Corporation support on this endpoint is in preview and may change in backwards-incompatible ways before it is marked stable. LLC support is stable. Avoid depending on the corporation behavior in production, and [reach out](mailto:support@getpalm.com) before building on it. Estimate the fees for a formation before submitting — useful for showing cost upfront or for billing reconciliation. Fees are broken down by component (`base`, `dynamic`, `late`, `credit_card`, `ach`); only the components that apply to the jurisdiction are returned. `fee.total` is the all-in grand total assuming credit-card payment (`base + dynamic + late + credit_card`), so you do not have to sum the components yourself. It is always an estimate. **Extra inputs.** Some states price the filing on share count, par value, authorized capital, or member count and need extra query parameters — for LLCs as well as corporations: - `authorized_shares` — required by CT/DE/KY/MA/MI/NM/RI/VA corporations - `par_value` and `par_value_type` — required by DE corporations; `par_value_type` is `par` or `no_par`, and `par_value` is the per-share par value in USD (must still be present when `no_par` — pass `0`, the value is ignored) - `authorized_capital` — total authorized capital in USD, required by DC/MO corporations - `pages` — document page count, required by DE corporations - `paid_in_capital` — required by IL corporations - `aggregate_par_value` — aggregate par value of all authorized stock (par value × authorized shares) in USD, required by MD corporations - `member_count` — number of LLC members, required by TN LLCs - `startup_for_soldiers` — `true` when the filer qualifies for Missouri’s Startup for Soldiers fee waiver (active-duty military in Missouri forming a new business), required by MO corporations - `is_subchapter_s` — `true` when the LLC elects (or will elect) federal S-corporation tax treatment; South Carolina then requires the CL-1 initial return and adds its $25 fee, required by SC LLCs - `expedited_tier` — optional; adds the expedited surcharge for that speed where the state offers expedited processing (tiers seen today: `expedited`, `24_hour`, `same_day`, `3_hour`, `2_hour`, `1_hour`); a tier the state does not offer returns `400`, the same as on the create endpoint Every input listed for a jurisdiction is required on every call — a `400` means the parameter was missing entirely. When an input does not apply to your filing, it must still be sent with a placeholder value: e.g. `par_value=0` when `par_value_type=no_par` (the value is ignored). Any other query parameter is also forwarded to the fee calculation as an extra input, so if a `400` lists a required input not documented here, supply it as a query parameter with that name. Numeric values and `true`/`false` are coerced from the query string automatically. Omit `expedited_tier` and, where the state offers expedited processing, the response includes `expedited_tiers`: a menu of `{ tier, fee }` where `fee` is the added surcharge as an `{ amount, currency }` pair (total cost = the standard fee components + `fee.amount`). Submit your chosen tier on the create endpoint via `expedited_tier`. If required inputs are missing, the endpoint returns `400` listing them. # Get formation requirements Source: https://docs.getpalm.com/api-reference/v1/filing/get-formation-requirements /api-reference/v1/openapi.json get /v1/filing/formation/requirement > **⚠️ Early access (corporations)** — Corporation support on this endpoint is in preview and may change in backwards-incompatible ways before it is marked stable. LLC support is stable. Avoid depending on the corporation behavior in production, and [reach out](mailto:support@getpalm.com) before building on it. Discover which fields a formation needs for a given jurisdiction and entity type. Call this before building a formation request so you know what to collect from the user. The response groups fields into: - **Common fields** — required everywhere (name, principal address, people, etc.) - **Jurisdiction-specific fields** — extra fields the state requires - **Available add-ons** — whether registered-agent service and EIN bundling are supported `expedited_tiers` lists the expedited processing tiers the state offers (the accepted `expedited_tier` values on create); price each one with the [formation fee endpoint](/api-reference/v1/filing/get-formation-fee-estimate). If Palm does not yet support formations in a jurisdiction, the jurisdiction-specific list comes back empty and submitting a formation there returns `501`. # List filings Source: https://docs.getpalm.com/api-reference/v1/filing/list-filings /api-reference/v1/openapi.json get /v1/filing List filings in your Palm account, ordered most-recent first. Filter by type, status, or linked business; paginate with the opaque `cursor` returned on the previous page. # Register an existing business in another state Source: https://docs.getpalm.com/api-reference/v1/filing/register-an-existing-business-in-another-state /api-reference/v1/openapi.json post /v1/filing/foreign-qualification > **⚠️ 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. 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](/api-reference/v1/filing/get-foreign-qualification-requirements) lists. A delayed `effective_date` is one of them: it is listed only for states that offer one, and sending it to a state that does not is rejected with a `400`, since dropping it would change when the registration takes effect. **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](/api-reference/v1/filing/cancel-a-filing). # Retrieve a filing Source: https://docs.getpalm.com/api-reference/v1/filing/retrieve-a-filing /api-reference/v1/openapi.json get /v1/filing/{filing_id} Retrieve a single filing by ID. The response includes its current status, the completion result (registration number for formations, EIN for EIN filings), the bundle of related obligations (`related_items` — EIN filings and the registered agent, each with its own status), cases that need your action (`cases`), generated documents, and recorded fees. # Validate a corporation formation request Source: https://docs.getpalm.com/api-reference/v1/filing/validate-a-corporation-formation-request /api-reference/v1/openapi.json post /v1/filing/formation/corporation/validate > **⚠️ 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. Check a corporation formation payload against state compliance rules without creating a filing or business record. Returns every compliance error in one pass, so you can pre-flight a submission. Accepts a partial or complete payload, including the same jurisdiction-specific fields as the create endpoint (extra top-level properties, plus `jurisdiction_registered_agent` and `jurisdiction_stock_structure` for state-specific fields). The [formation requirements endpoint](/api-reference/v1/filing/get-formation-requirements) lists what a given state expects. Any top-level field the state does not accept is reported under `warnings` — those are dropped rather than rejected when you create the filing, so this is the only place they show up. An `expedited_tier` the state does not offer is reported as an error at `expedited_tier` — the create endpoint rejects it with `400`. This checks state compliance rules only. Some field-format checks run on the create endpoint, so a payload that passes here can still be rejected when you submit it. # Validate a foreign qualification request Source: https://docs.getpalm.com/api-reference/v1/filing/validate-a-foreign-qualification-request /api-reference/v1/openapi.json post /v1/filing/foreign-qualification/validate > **⚠️ 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. Check a foreign qualification payload without creating a filing or business record. Runs the same checks as the create endpoint except the name check, and returns every finding in one pass: problems with the referenced business record (missing fields, not the formation-state registration, already registered in the target state), an expedited tier the state does not offer, and state compliance errors on the payload. Accepts a partial or complete payload, including the same state-specific fields as the create endpoint. Any top-level field the state does not accept is reported under `warnings`; those are dropped rather than rejected when you create the filing. The exception is `effective_date`: sent to a state that offers no delayed effective date, it is an error here (`unsupported`) and a `400` on create. The name check runs only on the create endpoint, so a payload that passes here can still be rejected there because the legal name is unavailable in the target state. # Validate an EIN application request Source: https://docs.getpalm.com/api-reference/v1/filing/validate-an-ein-application-request /api-reference/v1/openapi.json post /v1/filing/ein/validate Check an EIN application payload for field-shape errors without creating a filing — the same dry-run pre-flight the formation validate endpoints offer. Returns every field error in one pass, including the conditional `principal_activity` follow-ups for the selected category. Beyond field shape, the check loads the referenced business and applies the entity-type rules the IRS application branches on — the LLC member questions and the corporation subtype — so it agrees with the create endpoint on those. A field that does not apply to the business's entity type comes back as a warning and is ignored on submit. The responsible-party vault requirements still run only on the create endpoint, so a payload that passes here can still be rejected when you submit it. # Validate an LLC formation request Source: https://docs.getpalm.com/api-reference/v1/filing/validate-an-llc-formation-request /api-reference/v1/openapi.json post /v1/filing/formation/llc/validate Check an LLC formation payload against state compliance rules without creating a filing or business record. Returns every compliance error in one pass, so you can pre-flight a submission. Accepts a partial or complete payload, including the same jurisdiction-specific fields as the create endpoint (extra top-level properties, plus `jurisdiction_registered_agent` for state-specific registered-agent fields). The [formation requirements endpoint](/api-reference/v1/filing/get-formation-requirements) lists what a given state expects. Any top-level field the state does not accept is reported under `warnings` — those are dropped rather than rejected when you create the filing, so this is the only place they show up. An `expedited_tier` the state does not offer is reported as an error at `expedited_tier` — the create endpoint rejects it with `400`. This checks state compliance rules only. Some field-format checks run on the create endpoint, so a payload that passes here can still be rejected when you submit it. # Get business monitoring subscription status Source: https://docs.getpalm.com/api-reference/v1/monitor/get-business-monitoring-subscription-status /api-reference/v1/openapi.json get /v1/business/{business_id}/subscription Retrieve the current monitoring subscription status and configuration for a business. # Monitor business Source: https://docs.getpalm.com/api-reference/v1/monitor/monitor-business /api-reference/v1/openapi.json post /v1/business/subscription Subscribe to monitoring events for a business identified by `palm_id`, or by `registration_jurisdiction` with `registration_number`. Each identifier names one registration; a business registered in several jurisdictions is monitored per registration. The subscription is attached to the portfolio business already linked to that registration, or to one whose vault carries the same `registration_jurisdiction` and `registration_number`, which is then linked. When the organization holds neither, a business is created from the registry record. The business is returned with the subscription. # Monitor portfolio business Source: https://docs.getpalm.com/api-reference/v1/monitor/monitor-portfolio-business /api-reference/v1/openapi.json post /v1/business/{business_id}/subscription Subscribe to monitoring events for a business to receive real-time notifications about watchlist hits, registration updates, ownership changes, and other compliance events. # Unsubscribe from business monitoring Source: https://docs.getpalm.com/api-reference/v1/monitor/unsubscribe-from-business-monitoring /api-reference/v1/openapi.json delete /v1/business/{business_id}/subscription Cancel monitoring for a business. Events stop immediately, and a later POST restarts monitoring. To pause monitoring, use PATCH with status: paused. # Update business monitoring event types Source: https://docs.getpalm.com/api-reference/v1/monitor/update-business-monitoring-event-types /api-reference/v1/openapi.json patch /v1/business/{business_id}/subscription Update the event types, metadata, or status of a business subscription. Status may only be set to `active` or `paused` — to cancel a subscription, use the DELETE endpoint. # Change or end registered agent service Source: https://docs.getpalm.com/api-reference/v1/registered-agent/change-or-end-registered-agent-service /api-reference/v1/openapi.json patch /v1/business/{business_id}/registered-agent > **⚠️ 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. Updates the registered agent on a business. Both actions are discriminated by `status`: - `change_requested` — change the RA of record. Supply `registered_agent` to switch to your own / a different RA, or omit it to switch to Palm-provided service. The RA moves to `pending`; on completion `registered_agent.activated` (into Palm) or `registered_agent.changed` (away) fires. Any state-side filing this requires happens internally, in the state named by the business's `registration_jurisdiction`, which the business must have. Returns 409 if a registered agent operation is already in flight (`pending` or `termination_requested`). - `termination_requested` — ask Palm to stop serving as RA. Sets status to `termination_requested`; Palm remains RA on file and keeps forwarding mail until the work completes, when `registered_agent.terminated` fires. Returns 409 if the service is not currently `active`. In test mode both actions complete immediately: termination fires `registered_agent.termination_requested` and `registered_agent.terminated` and returns the terminal snapshot (`status: terminated`). # Retrieve registered agent service Source: https://docs.getpalm.com/api-reference/v1/registered-agent/retrieve-registered-agent-service /api-reference/v1/openapi.json get /v1/business/{business_id}/registered-agent > **⚠️ 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. Returns the current snapshot of the registered agent service on a business — provider, status, jurisdiction, and the current service window. Returns 404 when Palm has never been the registered agent for the business; once the service has ended it returns 200 with `status: terminated` — letting you tell "not your registered agent" apart from "service ended". # Check business name eligibility Source: https://docs.getpalm.com/api-reference/v1/registry/check-business-name-eligibility /api-reference/v1/openapi.json get /v1/business/registry/{registration_jurisdiction}/name-eligibility > **⚠️ 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. Check whether a prospective business name can be registered in a jurisdiction before filing a formation. Combines the jurisdiction's naming rules (required designators, prohibited and restricted words, character limits) with registry availability. Returns a single `eligible` answer plus `violations` explaining any naming-rule problems; an auto-fixable designator problem carries a `fix`. Pass `suggest=true` to also receive alternative name ideas in `alternatives`, and `screen=true` to also screen the name for content issues such as obscenity or deceptive similarity to a government agency; screening findings come back as `advisory` violations. # Get accepted name designators Source: https://docs.getpalm.com/api-reference/v1/registry/get-accepted-name-designators /api-reference/v1/openapi.json get /v1/business/registry/{registration_jurisdiction}/name-eligibility/designator > **⚠️ 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. List the name designators (also called suffixes) a jurisdiction accepts for each entity type — the `LLC`, `Inc.`, or `P.C.` a business name must carry to be filed there. Call this before collecting a name so you can offer the valid designators up front, or append one on the user's behalf, rather than discovering the requirement from a rejected name. Omit `entity_type` to receive every entity type in one response. A few jurisdictions mandate no designator for an entity type (California corporations, for one). Those return `required: false` with an empty `accepted` list, meaning a name may be filed with or without one. An entity type a jurisdiction does not permit at all is left out of the response (California offers no professional LLC, for one); the name-eligibility endpoint reports it as `entity_type_unavailable`. Designators are one of several naming requirements. A name carrying a valid designator can still be rejected for other reasons, so check the finished name with the name-eligibility endpoint before filing. # Get business from registry Source: https://docs.getpalm.com/api-reference/v1/registry/get-business-from-registry /api-reference/v1/openapi.json get /v1/business/registry/{registration_jurisdiction}/{registration_number} Retrieve a detailed business record from the registry by jurisdiction and registration number. Returns a fuller record than search, including connected people (associates), standing, fictitious names, and industry codes. # Search business registries Source: https://docs.getpalm.com/api-reference/v1/registry/search-business-registries /api-reference/v1/openapi.json post /v1/business/registry/search Search business registries to find registered businesses before verifying them. Records are drawn from authoritative sources — state registries, the IRS, and licensing agencies. Returns each match with its Palm ID, registration details (legal name, entity type, registration number, formation date, jurisdictions, and current status), and principal address. # Create a new user Source: https://docs.getpalm.com/api-reference/v1/user/create-a-new-user /api-reference/v1/openapi.json post /v1/user Creates a new user record with optional display name, metadata, and vault data. Vault fields use the `identity.*` key format (e.g., `identity.first_name`, `identity.email`). # Delete a user Source: https://docs.getpalm.com/api-reference/v1/user/delete-a-user /api-reference/v1/openapi.json delete /v1/user/{user_id} Deletes a user and their associated data. This performs a soft delete by default, setting the user status to deleted. # List businesses for a user Source: https://docs.getpalm.com/api-reference/v1/user/list-businesses-for-a-user /api-reference/v1/openapi.json get /v1/user/{user_id}/business Returns all businesses where this user is listed as a beneficial owner. # Retrieve a user Source: https://docs.getpalm.com/api-reference/v1/user/retrieve-a-user /api-reference/v1/openapi.json get /v1/user/{user_id} Retrieves a user by ID. Returns the user record with status, display name, and metadata. Personal data is stored encrypted or as fingerprints and is not returned in the response. # Search users Source: https://docs.getpalm.com/api-reference/v1/user/search-users /api-reference/v1/openapi.json post /v1/user/search Search for users in your organization with optional filters. Filter by display_name (partial match), or by email, phone, or SSN (exact match). Returns paginated results using cursor-based pagination. # Update a user Source: https://docs.getpalm.com/api-reference/v1/user/update-a-user /api-reference/v1/openapi.json patch /v1/user/{user_id} Updates a user's display name or metadata. Metadata updates are merged with existing values; set a key to null to remove it. # Verify existing user Source: https://docs.getpalm.com/api-reference/v1/user/verify-existing-user /api-reference/v1/openapi.json post /v1/user/{user_id}/verification # Retrieve business verification Source: https://docs.getpalm.com/api-reference/v1/verification/retrieve-business-verification /api-reference/v1/openapi.json get /v1/business/{business_id}/verification/{verification_id} # Retrieve user verification Source: https://docs.getpalm.com/api-reference/v1/verification/retrieve-user-verification /api-reference/v1/openapi.json get /v1/user/{user_id}/verification/{verification_id} # Verify business Source: https://docs.getpalm.com/api-reference/v1/verification/verify-business /api-reference/v1/openapi.json post /v1/business/verification Executes a configurable business verification workflow which utilizes authoritative sources (Secretary of State, IRS TIN matching, business registries), optionally verifies associated people, and returns risk assessment with field-level match results. The required fields are determined by the selected verification workflow. ## Response status The HTTP response is always `201`; the verification outcome is carried by `status` in the body, so check it first. - **`completed`** — Resolved immediately. `risk` and `match` are populated: a confident match returns the agreeing fields and a risk level, while a no-match returns an empty `match` with `risk.level: critical`. - **`in_progress`** — Could not be resolved immediately and is continuing asynchronously; `risk` and `match` are not yet set. Wait for the `business.verification.completed` webhook, which delivers the final result in this same shape. - **`failed`** — A system error occurred (rare); safe to retry. `risk` and `match` are only meaningful once `status` is `completed`. # Verify portfolio business Source: https://docs.getpalm.com/api-reference/v1/verification/verify-portfolio-business /api-reference/v1/openapi.json post /v1/business/{business_id}/verification # Verify TIN Source: https://docs.getpalm.com/api-reference/v1/verification/verify-tin /api-reference/v1/openapi.json post /v1/tin/verification Verifies a Tax Identification Number (EIN or SSN) and associated name against IRS records. Unlike `POST /business/verification`, this runs only the IRS TIN Matching check and does not perform registry lookup or risk assessment. When the IRS service is unavailable, returns `matched: null` with `status: pending` and a machine-readable `unavailable_reason` so callers can retry later. In test mode the check is always simulated — the IRS is never contacted, and `metadata._simulate` selects the outcome (see the `metadata` field). # Verify user identity Source: https://docs.getpalm.com/api-reference/v1/verification/verify-user-identity /api-reference/v1/openapi.json post /v1/user/verification Executes a configurable user verification workflow which utilizes authoritative sources, and returns risk assessment with field-level match results. # Business created Source: https://docs.getpalm.com/api-reference/v1/webhooks/business-created /api-reference/v1/openapi.json webhook business.created A business was added to your portfolio. `data.object` is the business as it stands after the change. # Business filing due Source: https://docs.getpalm.com/api-reference/v1/webhooks/business-filing-due /api-reference/v1/openapi.json webhook business.filing.due A compliance filing for a monitored business is coming due. `data.object` describes the filing and its due date; `data.business` identifies the business. # Business filing overdue Source: https://docs.getpalm.com/api-reference/v1/webhooks/business-filing-overdue /api-reference/v1/openapi.json webhook business.filing.overdue A compliance filing for a monitored business is past due. `data.object` describes the filing and its due date; `data.business` identifies the business. # Business registration updated Source: https://docs.getpalm.com/api-reference/v1/webhooks/business-registration-updated /api-reference/v1/openapi.json webhook business.registration.updated A monitored business changed on the registry: status, standing, entity type, name, address, agent, associates, filings or identifiers. `data.business` identifies the business and `data.changes` lists each change with a human-readable summary and the previous and current values. # Business removed Source: https://docs.getpalm.com/api-reference/v1/webhooks/business-removed /api-reference/v1/openapi.json webhook business.removed A business was removed from your portfolio. `data.object` is the business as it stands after the change. Status is `deleted`. # Business verification completed Source: https://docs.getpalm.com/api-reference/v1/webhooks/business-verification-completed /api-reference/v1/openapi.json webhook business.verification.completed A business verification finished. `data.object` is the verification result: risk level and reasons plus per-field match outcomes against the registry record. `completed` means the check ran, not that it passed; read `risk.level`. # Case opened Source: https://docs.getpalm.com/api-reference/v1/webhooks/case-opened /api-reference/v1/openapi.json webhook case.opened A case is awaiting your response for the first time. `data.object` is the case; `request.fields` lists what is needed. # Case resolved Source: https://docs.getpalm.com/api-reference/v1/webhooks/case-resolved /api-reference/v1/openapi.json webhook case.resolved A case reached a terminal state. `data.object` is the case; `resolution_reason` says how it closed. # Case updated Source: https://docs.getpalm.com/api-reference/v1/webhooks/case-updated /api-reference/v1/openapi.json webhook case.updated A case you can see changed hands, such as moving to `under_review` after your response, or Palm attached documents for you. `data.object` is the case. # Document created Source: https://docs.getpalm.com/api-reference/v1/webhooks/document-created /api-reference/v1/openapi.json webhook document.created Palm attached a new document to one of your resources, such as a filing artifact or forwarded registered-agent mail. `data.object` is the document; route by its `types`. # Document request completed Source: https://docs.getpalm.com/api-reference/v1/webhooks/document-request-completed /api-reference/v1/openapi.json webhook document_request.completed A document request delivered its document. `data.object` is the document request; `documents` lists the delivered files. # Document request failed Source: https://docs.getpalm.com/api-reference/v1/webhooks/document-request-failed /api-reference/v1/openapi.json webhook document_request.failed A document request ended without its document. `data.object` is the document request; `failure_reason` says why. # Document request processing Source: https://docs.getpalm.com/api-reference/v1/webhooks/document-request-processing /api-reference/v1/openapi.json webhook document_request.processing A document request is being fulfilled. `data.object` is the document request as it stands after the change. # Document updated Source: https://docs.getpalm.com/api-reference/v1/webhooks/document-updated /api-reference/v1/openapi.json webhook document.updated A document already on one of your resources changed: Palm identified new `types` for it, or a document you uploaded is now part of a case you can see. `data.object` is the document; `related_items` names the case and filing. # Filing canceled Source: https://docs.getpalm.com/api-reference/v1/webhooks/filing-canceled /api-reference/v1/openapi.json webhook filing.canceled A filing was canceled before completion. `data.object` is the filing as it stands after the change. `status_reason` and `canceled_by` say why and by whom. # Filing completed Source: https://docs.getpalm.com/api-reference/v1/webhooks/filing-completed /api-reference/v1/openapi.json webhook filing.completed A filing was accepted by the authority. `data.object` is the filing as it stands after the change. `result` carries the outcome and `documents` the artifacts. # Filing filed Source: https://docs.getpalm.com/api-reference/v1/webhooks/filing-filed /api-reference/v1/openapi.json webhook filing.filed A filing was submitted to the authority and is awaiting its decision. `data.object` is the filing as it stands after the change. # Filing processing Source: https://docs.getpalm.com/api-reference/v1/webhooks/filing-processing /api-reference/v1/openapi.json webhook filing.processing A filing is being prepared or is waiting on the authority. `data.object` is the filing as it stands after the change. # Filing queued Source: https://docs.getpalm.com/api-reference/v1/webhooks/filing-queued /api-reference/v1/openapi.json webhook filing.queued A filing was accepted and is waiting to be prepared. `data.object` is the filing as it stands after the change. # Filing ready to file Source: https://docs.getpalm.com/api-reference/v1/webhooks/filing-ready-to-file /api-reference/v1/openapi.json webhook filing.ready_to_file A filing has everything it needs and is about to be submitted. `data.object` is the filing as it stands after the change. # Registered agent activated Source: https://docs.getpalm.com/api-reference/v1/webhooks/registered-agent-activated /api-reference/v1/openapi.json webhook registered_agent.activated Palm became the registered agent for a business, either through a formation or a change into Palm completing. `data.object` is the registered agent record; status is `active`. # Registered agent canceled Source: https://docs.getpalm.com/api-reference/v1/webhooks/registered-agent-canceled /api-reference/v1/openapi.json webhook registered_agent.canceled A pending registered agent was canceled on request before Palm became the agent, for example because the formation filing was canceled. Status is `canceled` and `rejection_reason` carries the reason. # Registered agent change failed Source: https://docs.getpalm.com/api-reference/v1/webhooks/registered-agent-change-failed /api-reference/v1/openapi.json webhook registered_agent.change_failed A requested registered agent change could not be completed. The change never applied, so status returns to what it was before the request and the agent of record is unchanged; `rejection_reason` carries the explanation. # Registered agent changed Source: https://docs.getpalm.com/api-reference/v1/webhooks/registered-agent-changed /api-reference/v1/openapi.json webhook registered_agent.changed A change away from Palm completed and Palm is no longer the registered agent for the business. `data.object` is the registered agent record; status is `terminated` and provider is `external`. # Registered agent failed Source: https://docs.getpalm.com/api-reference/v1/webhooks/registered-agent-failed /api-reference/v1/openapi.json webhook registered_agent.failed Initial registered agent provisioning could not be completed. Status is `failed` and `rejection_reason` carries the explanation. # Registered agent terminated Source: https://docs.getpalm.com/api-reference/v1/webhooks/registered-agent-terminated /api-reference/v1/openapi.json webhook registered_agent.terminated The termination completed and Palm is no longer the registered agent on file. Status is `terminated` and `ended_at` carries the close timestamp. # Registered agent termination failed Source: https://docs.getpalm.com/api-reference/v1/webhooks/registered-agent-termination-failed /api-reference/v1/openapi.json webhook registered_agent.termination_failed A termination could not be completed. Status reverts to `active` and `rejection_reason` carries the explanation; submit a new request once the blocker is resolved. # Registered agent termination requested Source: https://docs.getpalm.com/api-reference/v1/webhooks/registered-agent-termination-requested /api-reference/v1/openapi.json webhook registered_agent.termination_requested You asked Palm to stop acting as registered agent. Status is `termination_requested`; Palm remains the agent on file and keeps forwarding mail until the termination completes. # Session completed Source: https://docs.getpalm.com/api-reference/v1/webhooks/session-completed /api-reference/v1/openapi.json webhook session.completed An onboarding session reached the end of its workflow. `data.object` is the session as it stands after the change. # User created Source: https://docs.getpalm.com/api-reference/v1/webhooks/user-created /api-reference/v1/openapi.json webhook user.created A person was added to your portfolio. `data.object` is the user as it stands after the change. # User removed Source: https://docs.getpalm.com/api-reference/v1/webhooks/user-removed /api-reference/v1/openapi.json webhook user.removed A person was removed from your portfolio. `data.object` is the user as it stands after the change. Status is `deleted`. # User verification completed Source: https://docs.getpalm.com/api-reference/v1/webhooks/user-verification-completed /api-reference/v1/openapi.json webhook user.verification.completed A person verification finished. `data.object` is the verification result: risk level and reasons, per-field match outcomes, synthetic-identity and watchlist findings. `completed` means the check ran, not that it passed; read `risk.level`. # Changelog Source: https://docs.getpalm.com/changelog Latest updates and improvements to the Palm API Stay up to date with new features, improvements, and bug fixes to the Palm Platform. ## Week of October 19, 2026 **Onboard**: The name check and the accepted endings now follow each state's own naming law. The check now flags names that signal a regulated profession and, where the state requires it, names that differ from a registered business only in their ending. See [Check name eligibility](/onboard/name-eligibility). **Registered Agent**: Fixed registered agent change requests being rejected for businesses that have a registration jurisdiction but no formation jurisdiction. ## Week of October 12, 2026 **Webhooks**: Test events you send from the dashboard now carry a sample payload shaped like the real event, so you can check your handler for each event type before live traffic arrives. The dashboard shows a preview of the payload before you send it. ## Week of October 5, 2026 **Formations & Filings**: You can now include a note when you submit a filing, so Palm's filing team has your context before it files. The note stays on the filing for later reference. **Webhooks**: Documents you upload to Palm now reach your webhook the same way as documents Palm adds. A new `document.updated` event tells you when a document changes, such as when it is attached to a case. **Cases**: You can now run name-change and document cases in test mode, so you can build your case handling before you meet one on a live filing. ## Week of September 21, 2026 **Cases**: Palm can now ask you for documents on a case as well as information, and you can answer with files you have uploaded. A new `legal_name_change` case kind tells you when a case will change the business name being filed, so you can update the name in your own records. **Business**: Documents now show which filing or case they belong to, and you can list a business's documents by filing or by case. **Formations & Filings**: Tennessee LLC formations now require an explicit answer to the Obligated Member Entity election. You can now set a delayed effective date, with an optional effective time, on Colorado, Georgia, Iowa, and Tennessee formations. The business name is now `legal_name` on formation requests, filings, and EIN results. `entity_name` on formation requests and `name` on filings are deprecated but still supported. ## Week of September 14, 2026 **MCP Server**: Palm's MCP server now supports person verification alongside business verification. **Business**: A document can now carry more than one type, so a single file that is both a receipt and a filing confirmation is labeled as both. `type` is deprecated in favor of `types`. **Formations & Filings**: EIN applications for corporations now accept the corporation subtype, such as S Corporation, and EIN applications bundled with an LLC formation now accept the number of LLC members. ## Week of September 7, 2026 **Monitor**: You can now start monitoring a business without verifying it first — send a Palm ID, or a jurisdiction and registration number, and Palm adds the business to your portfolio for you. **Webhooks**: The `document.created` event now names the resource a document belongs to, so you can route forwarded registered-agent mail to the right business the moment it arrives. The same details are returned when you retrieve or list a document. **Formations & Filings**: Documents delivered on a completed filing now carry more granular types, so you can identify each one by type rather than by file name. ## Week of August 31, 2026 **Formations & Filings**: Formation documents now carry more specific types, so the state's filing confirmation and welcome letter are identifiable programmatically. **Registered Agent**: Cancelling a formation now cancels its pending Palm registered-agent service as a first-class operation, with its own terminal status and a new `registered_agent.canceled` webhook. **Registry**: You can now look up the name designators a jurisdiction accepts for each entity type, so you can offer valid options up front or append one yourself instead of discovering the rule from a rejected name. The endpoint is in early access. ## Week of August 10, 2026 **Formations & Filings**: You can now cancel a filing before it enters processing — cancelling a formation that hasn't started also cancels its related pending filings, such as the EIN. Formation requirement schemas now carry titles, descriptions, and readable option labels on every field, so you can render them directly in your own forms. Fee estimates now include state card-payment convenience fees in Maryland and Wyoming. ## Week of August 3, 2026 **Registry**: Registry search now filters on two finer entity types — professional LLC and professional corporation. **Formations & Filings**: LLC formation, EIN, and filing endpoints are now out of early access. Corporation formation stays in early access for now. You can also send an idempotency key with a filing submission, so a retry returns the original filing instead of creating a second one. **Registered Agent**: Forwarded documents now carry a more precise document type, making service of process, state notices, and formation records straightforward to route on. ## Week of July 20, 2026 **Formations & Filings**: The EIN application now supports capturing a spouse or registered domestic partner in the community-property states that require it. Fee estimates now include convenience and processing fees, so estimated totals match what's actually charged. ## Week of July 13, 2026 **Name Eligibility**: You can now check whether a proposed business name will be accepted before filing, across all 50 states and DC. One response returns an eligible/not-eligible answer with plain-language reasons and availability, for LLCs, Corporations, and their professional variants. **Formations & Filings**: The formation requirements endpoint now reports entity contact fields under their canonical names (`email`, `phone`, and `website`) and marks required contact fields accurately, matching what formation submission expects. **API**: Test mode can now simulate verification and filing outcomes deterministically: set the reserved `_simulate` control on a test-key request to drive a specific result. **Registered Agent**: Registered-agent changes and terminations now return their documents via the `document.created` event, so you can retrieve them without polling. ## Week of July 6, 2026 **API**: Test mode is here: every API key and Console view now resolves to test or live, with all data partitioned by mode so test activity never touches production. **Registered Agent**: Registered Agent is now its own resource with its own status lifecycle, and new registered-agent webhook events track it from creation through every change. **Formations & Filings**: A formation now exposes a related-items view: each part of the bundle reports its own status, plus an overall completion rollup. ## Week of June 29, 2026 **Registry**: Business registry detail lookups now return a grouped `identifier` object that surfaces additional well-known identifiers Palm already holds for a business: the Legal Entity Identifier (`identifier.lei`), the SEC EDGAR identifier (CIK), the Canadian Business Number, and the state taxpayer number, so you can cross-reference a business against external registries like GLEIF and SEC EDGAR directly from our response. Only identifiers that are present for a given business are included, keeping the payload lean. **Formations & Filings**: The EIN application now captures the IRS's conditional Form SS-4 questions as structured fields, covering the category-specific principal-activity follow-ups and employee-count details, so a complete application can be submitted in a single request; you can also dry-run validate an EIN application before submitting it. Fee estimates and the `filing.completed` event now include a total fee alongside the line-item breakdown. **Webhooks**: You can now replay past webhook events for a chosen time range, self-serve from the Console and via the API, giving you a standard way to recover deliveries after an outage on your side. Endpoints that are automatically disabled after sustained delivery failures now also send an email alert so you know to step in. ## Week of June 22, 2026 **Registry**: Registry search can now start from a person, not just a business. Pass a person's name and you get back every business they're connected to (as an officer, director, manager, member, or registered agent) which makes due-diligence and KYB workflows much easier. You can also filter registry search by Palm ID to jump straight to a business you've already seen. **Formations & Filings**: **Breaking:** filing documents are now referenced by a document ID rather than a URL. Update any integration that reads document URLs from filing responses. ## Week of June 15, 2026 **Formations & Filings**: The formation requirements endpoint now returns fully self-contained schemas. Unresolved `$ref`s are gone, so you can parse requirements directly without dereferencing external pointers. ## Week of June 8, 2026 **Formations & Filings**: The Formations & Filings API is live. You can form LLCs and Corporations programmatically end to end: apply for an EIN, check name availability, pull state-aware filing requirements, get fee estimates before you file, and track each filing through its full status lifecycle, with webhooks firing on every status change. **Registered Agent**: The Registered Agent API launched alongside it. Retrieve an agent's status, name, and address, and request an RA change or termination through the API. Lifecycle webhooks (`registered_agent.activated`, `.changed`, `.termination_requested`, and `.terminated`) keep your systems in sync as things change. **Webhooks**: A new `document.created` event fires the moment a document becomes available on a business, so you can react without polling. We also fixed `filing.completed` so it always includes the `fee` field, which could previously come back null. **Verify**: Identity verification scoring got more accurate, cutting down false positives on legitimate individuals. ## Week of May 25, 2026 **Formations & Filings**: Filings that need extra information now drive an information-request flow, giving you a structured way to collect and submit the missing fields. **Verify**: Improved EIN matching during business verification. **Webhooks**: Webhook signature headers are now matched case-insensitively, which fixes signature verification for HTTP clients that normalize header casing. **Business**: You can now delete a business through the API, so you can clean up records you no longer need to track on your own. ## Week of May 18, 2026 **Verify**: When several businesses look alike, verification now disambiguates between them and resolves to the best match more reliably. **Formations & Filings**: Filings can now report exception statuses, giving you a clearer signal when one needs attention. ## Week of April 13, 2026 **Single Sign-On for Palm Console** Users can now access the Palm Console with their Google account, removing password friction. **Public Developer Documentation** Palm's API and product capabilities can be evaluated directly, without gating or access requests. **Monitor Next Actions** On top of registry change events, Monitor now surfaces the specific next compliance action a business needs to take. **Usage-Based Pricing** Palm now meters API usage across verification, registry search and detail, and monitoring subscriptions. ## Week of January 19, 2026 **Registry API Updates** * New endpoint: `GET /v1/business/registry/{jurisdiction}/{registration_number}` - Retrieve business details directly by registration number * Registry search endpoint path updated to `/v1/business/registry/search` (the previous path `/v1/business/registry-search` is deprecated but still supported) **Webhook Events** Standardized webhook event types for clearer, more consistent notifications: * `user.created` - New user added * `user.removed` - User deleted * `user.verification.completed` - User identity verification finished * `business.created` - New business added * `business.removed` - Business deleted * `business.verification.completed` - Business verification finished * `business.registration.updated` - Secretary of State registration changed * `business.filing.due` - Upcoming filing deadline * `business.filing.overdue` - Missed filing deadline * `session.completed` - Onboarding session finished ## Breaking Changes We take backward compatibility seriously. Any breaking changes will be: 1. Announced at least 3 months in advance 2. Documented with migration guides 3. Supported in a new API version 4. Available for testing before production rollout ## Report Issues Found a bug or have a feature request? * Email us at [support@getpalm.com](mailto:support@getpalm.com) * Check our [API Status Page](https://status.getpalm.com) * Review the [documentation](/api-reference/introduction) # Apply for an EIN Source: https://docs.getpalm.com/comply/apply-for-an-ein Get an Employer Identification Number from the IRS for any business — formed through Palm or not. An EIN is the tax identification number the IRS assigns to a business entity. A business needs one before it can hire, open a bank account, or file a return, so for most newly formed entities it is the step immediately after formation. Palm collects the information the IRS asks for on Form SS-4, submits the application, and returns the assigned number and the confirmation letter. *** ## Standalone or bundled Standalone. Apply for any business already in Palm. The business does not need to have been formed through Palm. It needs a business record with the required fields populated. Bundled with a formation. Pass an `ein` object on a [formation request](/comply/form-a-business#add-ons). Palm creates the EIN filing alongside the formation, holds it in `queued` until the formation completes, then advances it on its own. Both paths run the same lifecycle and return the same result. ## Before you apply The application reads from the business record rather than from your request, so the record has to be complete first. Palm needs the legal name, entity type, formation jurisdiction, formation date, and principal address. If any of them is missing, Palm rejects the request and names the fields it needs. Create the business first with `POST /v1/business` if it is not in Palm yet. ## The responsible party Every EIN application names a **responsible party**: the individual the IRS holds accountable for the entity. The IRS requires a person here, not a company, and expects their taxpayer identification number. You can supply them two ways: * **By reference.** Pass `user_id` for a user who already has a first name, last name, and SSN on record. * **Inline.** Pass the first name, last name, and SSN directly. Palm creates the user, vaults the SSN, and links them to the business. > [!NOTE] > > The responsible party must have a US taxpayer identification number to apply through this endpoint. For an application where the responsible party does not have one, [contact us](mailto:support@getpalm.com). ## What the application asks for The request mirrors Form SS-4, so the fields are the ones the IRS asks about: * **The entity.** Which business the EIN is for. * **The reason.** Why it needs one, such as starting a new business, hiring employees, or opening a bank account. * **How it operates.** Fiscal year end, employees expected over the next twelve months, and the principal business activity. * **Prior history.** Whether the entity has held an EIN before. For the exact fields, types, and conditional requirements, see [Apply for an EIN](https://docs.getpalm.com/api-reference/v1/filing/apply-for-an-ein). ## Validate before you submit ```bash Bash wrap theme={null} POST /v1/filing/ein/validate ``` Validation checks the shape of the request and returns every field error in one pass, including the follow-up fields a given `principal_activity` requires, without creating a filing. ## Submit and track ```bash Bash wrap theme={null} POST /v1/filing/ein GET /v1/filing/{filing_id} GET /v1/filing?type=ein&business_id={id} ``` The filing follows the same [lifecycle](/comply/overview#the-lifecycle) as every other Comply filing, and a `filing.*` webhook fires at each transition. If the IRS needs something the application did not carry, Palm opens a [case](/comply/cases) and sends a `case.opened` webhook. ## The result On `completed`, the filing carries the assigned EIN and the confirmed entity name under `result`, along with the IRS confirmation letter (CP 575) as a document. Palm also writes the EIN to the business record, so the number is available on the business itself rather than only on the filing. ## Next steps Form a business Bundle an EIN with a formation filing. [Open](/comply/form-a-business) Cases Respond to information requests Palm raises on a filing. [Open](/comply/cases) Webhooks Receive real-time status updates as the application progresses. [Open](/developer-guide/webhooks) Apply for an EIN reference Full reference for the EIN application endpoint. [Open](/api-reference/v1/filing/apply-for-an-ein) # Cases Source: https://docs.getpalm.com/comply/cases Respond to information requests Palm raises on a filing, and exchange the documents that go with them. Most filings complete on the original request alone. When something comes up that the request could not have anticipated, Palm opens a **case** on the filing rather than failing it. The prompt comes from the state, from the IRS, or from a decision only the business owner can make. Palm states what it needs as a structured list, you answer through the API, and the filing continues from where it stopped. The exchange stays on the filing instead of moving to email. *** ## How it works 1. Palm opens a case on the filing and sends a `case.opened` webhook. 2. Read what it asks for. Each case carries a list of the values and documents Palm needs, and any file Palm is sending you. 3. Collect the answers from your member, rendering your prompts from that list. 4. Submit the response, keying each answer by the name Palm asked for. 5. Palm acts on it and the filing continues. ## What a case asks for Cases are exceptions, and exceptions do not come from a fixed list. Rather than define one, Palm sends each case with its own description of what it needs, so a situation nobody anticipated arrives in a shape you already know how to read. Every case carries a `kind`. There are two. `missing_information` is the general kind, raised when a filing needs something the request did not carry: an address the state will not accept, a detail a state asks for but does not publish as a requirement, a document only the business owner holds. It lists what Palm needs under `request.fields`, each entry carrying the prompt to show and the type of answer expected, which may be a value or a document. `legal_name_change` is raised when the state will not accept the name on the filing, most often because another business registered it first, or because the state judges it too close to an entity already on the register. It asks for one field, `legal_name`, and nothing else. Because that shape is fixed, Palm acts on the answer directly: it renames the filing, any bundled filing not yet submitted so a pending EIN application follows the new name, and the business record. `filing.legal_name` always reports the name the filing completed under. For the exact object and field definitions, see [Retrieve a case](/api-reference/v1/case/retrieve-a-case). ## Documents on a case Documents move in both directions, so the evidence behind a request and the answer to it both stay on the filing. From Palm. `request.documents` carries the ids of any files Palm is sending you, so the evidence behind a request travels with it and you can see what Palm saw. Retrieve each one through the [document endpoints](/api-reference/v1/documents/retrieve-document-metadata). From you. A `document` field is answered with a file [uploaded to the business](/api-reference/v1/business/upload-document). The response carries anything else worth sending with it: the certificate for a name the member reserved with the state, a written approval a regulator issued, or a form the state requires the member to sign themselves. Either way the document is bound to the work it belongs to. `related_items` on the document names the case, and the filing behind it, so a file is traceable to the filing it was sent for long after the case closes. The same relationship is available as a filter. ```bash Bash wrap theme={null} GET /v1/business/{business_id}/document?case_id={case_id} GET /v1/business/{business_id}/document?filing_id={filing_id} ``` Documents on a case are readable only by the organization the case belongs to. See [List documents](/api-reference/v1/business/list-documents) for the full parameter set. ## Respond to a case ```bash Bash wrap theme={null} POST /v1/case/{case_id}/response ``` The `case.opened` payload carries the whole case. Submit while the case is still `needs_response`, keying each answer by the name Palm asked for. A successful submission hands the case back to Palm. When the work behind it finishes, Palm closes the case. For the request body, see [Submit a response to a case](/api-reference/v1/case/submit-a-response-to-a-case). ## Track a case ```bash Bash wrap theme={null} GET /v1/case/{case_id} GET /v1/case?parent_type=filing&parent_id={filing_id}&status=needs_response ``` Group the statuses by what each one asks of you. Waiting on you. `needs_response` is the only status that accepts a response, and the only point in a filing that blocks on you. Waiting on Palm. `under_review` means your answer arrived and Palm is acting on it. Finished. `resolved` when the work moved forward, `superseded` when the filing behind the case stopped first. `resolution_reason` records which. ```text theme={null} needs_response ⇄ under_review → resolved | superseded ``` A `case.*` webhook fires at each transition, so you can drive your UI from events rather than polling: `case.opened` when Palm needs you, `case.updated` when an open case changes, and `case.resolved` when it closes. Each payload carries the full case object, including any documents on it. See [Webhooks](/developer-guide/webhooks) for delivery, retries, and signature verification. ## Build against cases in test mode Cases are rare on live filings, so test mode lets you open one on demand. Set `metadata._simulate` on a test filing and it pauses at the status you choose and opens the case you name: an information request that asks for a field of your filing request, a `legal_name_change` case whose answer renames the filing and the business, or a case that carries a document from Palm and asks for one back. You respond through the same endpoints, and the same `case.*` webhooks fire. ```json wrap JSON theme={null} { "metadata": { "_simulate": "completed:case_processing:legal_name_change" } } ``` See [Test mode](/get-started/test-mode#simulating-outcomes) for every scenario and what each response does. ## Next steps Form a business State formation filings, end to end. [Open](/comply/form-a-business) Apply for an EIN Get an EIN from the IRS, standalone or bundled. [Open](/comply/apply-for-an-ein) Comply overview How filings, cases, and documents fit together. [Open](/comply/overview) Case API reference Full reference for the case endpoints. [Open](/api-reference/v1/case/retrieve-a-case) # Form a business Source: https://docs.getpalm.com/comply/form-a-business Register a new LLC or Corporation with any US state — Palm handles the filing end to end. Palm prepares the state-specific documents, submits them, and returns the registration number and confirmation documents when the state accepts the filing. Palm creates the business record at submission, so the entity is available for [verification](/verify/verify-a-business) and [monitoring](/monitor/overview) before the filing completes. *** ## How it works 1. Discover requirements. Ask what a given state needs for the entity type you are forming, and what it costs. 2. Validate. Check the payload against the state's rules before you commit to it. 3. Submit. Palm creates a filing and a business record. 4. Track. Follow the filing through its [lifecycle](/comply/overview#the-lifecycle), driven by webhooks. 5. Retrieve the result. Collect the registration number and documents on completion. ## Discover requirements Requirements differ substantially between states, so read them rather than hardcoding a field list. ```bash Bash wrap theme={null} GET /v1/filing/formation/requirement?entity_type=llc&jurisdiction=US-NC GET /v1/filing/formation/requirement?entity_type=corporation&jurisdiction=US-DE ``` The response carries a JSON Schema for the request body in that jurisdiction and entity type, plus the expedited processing tiers the state offers. Some states require fields no other state asks for, and those arrive as additional top-level properties on the formation request. Build your collection flow from this response so you ask a member only for what the target state needs. A field that is mandatory in Delaware may not exist in North Carolina. See [Get formation requirements](https://docs.getpalm.com/api-reference/v1/filing/get-formation-requirements). > [!NOTE] > > Palm does not advise which entity type a business should choose. You send the formation request with the entity type already decided. ### Price the filing To show a member a cost before they commit, call the [fee endpoint](https://docs.getpalm.com/api-reference/v1/filing/get-formation-fee-estimate). Several states price on inputs you supply, such as authorized shares or par value. Every figure returned before submission is an estimate. Where a state offers expedited processing, the fee response prices each available tier. Pass your chosen tier as `expedited_tier` on the formation request. See [Fees and expedited processing](/comply/overview#fees-and-expedited-processing). ## Validate before you submit ```bash Bash wrap theme={null} POST /v1/filing/formation/llc/validate POST /v1/filing/formation/corporation/validate ``` Validation checks a payload against the state's compliance rules and returns every error in one pass, without creating a filing or a business record. It accepts a partial payload, which makes it usable for inline validation while a member is still filling in your form. ## Submit the formation ```bash Bash wrap theme={null} POST /v1/filing/formation/llc # form an LLC POST /v1/filing/formation/corporation # form a C-Corp ``` Palm validates the request synchronously and returns specific errors for missing or malformed fields. On success, Palm creates: * A **filing** in `queued` status. * A **business record**, available through the Business API straight away. * A **user record** for everyone you list as an organizer, incorporator, director, or officer, each bound to the business as an owner. ### Add-ons * **Registered agent.** Omit the `registered_agent` block and Palm provides the service. Pass it to name your own agent. See [Registered agent](/comply/registered-agent). * **EIN.** Pass an `ein` object and Palm applies to the IRS once the formation completes. See [Apply for an EIN](/comply/apply-for-an-ein). Both appear under `related_items` on the filing and progress independently: the EIN as its own filing, the Palm registered agent as a registered agent resource. ## Track the filing ```bash Bash wrap theme={null} GET /v1/filing/{filing_id} GET /v1/filing?type=formation&status=processing&business_id={id} ``` A `filing.*` webhook fires at every status transition, so you can drive your UI from events rather than polling. If Palm needs something to finish the filing, it opens a [case](/comply/cases) and sends a `case.opened` webhook. For what each status asks of you, see [the lifecycle](/comply/overview#the-lifecycle). ## Retrieve the result On `completed`, the filing carries the state-assigned registration number and formation date, plus the documents the filing produced: articles of organization or incorporation, the state certificate, and receipts. See [Retrieve a filing](https://docs.getpalm.com/api-reference/v1/filing/retrieve-a-filing) for the full response. > [!NOTE] > > **After the formation.** Some states attach further obligations to a newly formed entity. New York, for example, requires new LLCs to publish notice of formation. Other states fold a tax or payroll registration into the formation itself. Palm handles both as part of the filing. ## Next steps Apply for an EIN Standalone, or bundled with a formation. [Open](/comply/apply-for-an-ein) Registered agent Provision the service, receive forwarded mail, and manage changes. [Open](/comply/registered-agent) Check name eligibility Catch naming problems before a member commits to a name. [Open](/onboard/name-eligibility) Cases Respond to information requests Palm raises on a filing. [Open](/comply/cases) Form an LLC Full reference for the LLC formation endpoint. [Open](/api-reference/v1/filing/form-an-llc) Form a corporation Full reference for the corporation formation endpoint. [Open](/api-reference/v1/filing/form-a-corporation) # Comply overview Source: https://docs.getpalm.com/comply/overview Act on behalf of businesses — formation, filings, registered agent services, and reinstatement through the same API you use to verify and monitor. Comply is where Palm writes. [Onboard](/onboard/overview) finds a business, [Verify](/verify/overview) confirms it, and [Monitor](/monitor/overview) watches it. Comply acts on it, submitting filings to the authority on the business's behalf and writing the confirmed result back to the record you already hold. Every accepted filing returns state-confirmed data to that same record, which keeps it current long after the initial verification. ![Image showcasing a confirmation screen for a filing.](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/ComplyOverviewEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=8b6363efd9ccd947fd3a6a1510d3ec75) *** ## The compliance lifecycle Every business registered with a US state moves through the same three stages. Formation. A business becomes a legal entity when a state accepts its formation filing. Until then it cannot open accounts, sign contracts, or hold assets in its own name. Most businesses also need an EIN, the IRS-assigned tax identification number, before they can hire, bank, or file taxes. Ongoing compliance. Registration is not permanent. States require periodic filings and fees to keep an entity in good standing, and every state-registered business must name a registered agent to receive legal and government documents. When a required filing is missed, the state can suspend or administratively dissolve the registration. A suspended entity is a live problem for anyone who lends to it, banks it, or relies on its standing. Remediation. A business that has lost good standing can usually recover it, but recovery is rarely a single form. States generally require the missed filings, the outstanding fees, and a penalty before they will restore the registration. ## What you can do through the API Comply does three things today. | Capability | What it does | | - | - | | [Form a business](/comply/form-a-business) | File an LLC or C-Corp formation with any US state, with EIN and registered agent as add-ons. | | [Apply for an EIN](/comply/apply-for-an-ein) | Submit an EIN application to the IRS, standalone or bundled with a formation. | | [Registered agent](/comply/registered-agent) | Offer registered agent service to your members' businesses, and receive the mail the state sends through the API. | Palm's compliance infrastructure maps the filing requirements, deadlines, fee structures, and submission processes for all 50 US states and DC. For the entity types available today, see [Form an LLC](https://docs.getpalm.com/api-reference/v1/filing/form-an-llc) and [Form a corporation](https://docs.getpalm.com/api-reference/v1/filing/form-a-corporation). ## How Comply connects to Onboard, Verify, and Monitor ![Representation of how comply falls within the Palm product suite.](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/GeneralPalmOutline.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=56b2ec60e41ae1af5d984b2d07ddfaa4) | Product | Role | | - | - | | Onboard | Find the business. Pull registration data. | | Verify | Verify the business. Confirm identity and standing. | | Monitor | Watch the business. Subscribe to changes. | | Comply | Act on the business. File, and write the result back. | Each product feeds the next. A business formed through Comply is immediately available to Verify and Monitor without re-entering data, and a standing change surfaced by Monitor tells you a business needs action. Because every accepted filing updates the record with state-confirmed data, the record stays current through compliance work the business already has to complete. ## How filings work Forming a business and applying for an EIN each create a **filing**: a tracked record that carries its own status, fees, cases, and documents. The filing object is generic. The lifecycle, the case mechanism, and document delivery work the same way no matter what Palm files. > [!NOTE] > > Registered agent service is not a filing. Palm tracks it on its own resource at `GET /v1/business/{business_id}/registered-agent`, with its own lifecycle. See [Registered agent](/comply/registered-agent). ### The lifecycle When nothing interrupts it, a filing takes this path: ```text theme={null} queued → ready_to_file → processing → filed → completed ``` Group the statuses by what each one asks of you. In flight. `queued`, `ready_to_file`, `processing`, and `filed` all mean Palm is working. A `filing.*` webhook fires at each transition, so you can drive your UI from events rather than polling. Waiting on you. A case is open on the filing. This is the only state that blocks on you, and Palm tracks it separately from status. See below. Finished. On `completed`, the result holds the registration number for a formation or the EIN for an application. The other terminal statuses mean the filing stopped, and `status_reason` says why. For the full status list and the shape of every field, see [Retrieve a filing](https://docs.getpalm.com/api-reference/v1/filing/retrieve-a-filing). ### When Palm needs something from you Most filings finish on the original request alone. When Palm needs something more, a correction or a detail not collected at submission, it opens a **case** on the filing and notifies you with a `case.opened` webhook. The request arrives as a description of what Palm needs, whether that is a value or a document, so you can render the prompt directly from the payload. See [Cases](/comply/cases) for the lifecycle and how to respond. ### Documents A completed filing carries the documents it produced: articles of organization or incorporation, IRS confirmation letters, state certificates, and receipts. Retrieve each through the Documents API for as long as you hold the record. ## Fees and expedited processing Filing fees vary by state, entity type, and filing method, and several states price a filing on inputs specific to that state: authorized shares, par value, authorized capital, member count. Palm exposes this through a dedicated fee endpoint rather than a static table, so you can show a member a cost before they commit. > [!NOTE] > > **Every fee returned before submission is an estimate.** Where a state prices a filing on inputs you supply, Palm applies that state's rules to calculate the estimate. Palm sets the final amount when the filing completes and sends it with the `filing.completed` webhook. The receipt on the completed filing is the source of truth. Where a state offers expedited processing, the fee response returns the available tiers and the surcharge for each, and you submit your chosen tier with the formation request. See [Get formation fee estimate](https://docs.getpalm.com/api-reference/v1/filing/get-formation-fee-estimate) for the required inputs per jurisdiction. ## Validate before you submit Every filing type has a matching validate endpoint that checks a payload against the state's compliance rules without creating a filing or a business record. It returns every compliance error in one pass, which makes it well suited to inline validation in your collection flow, so a member fixes the problem while they are still in the form rather than after the filing is queued. ## Before you begin * A Palm API key. [Get access](/get-started/get-access) * For formation, the business data the target state requires. * For EIN, an existing business record with the required fields populated. > [!NOTE] > > **Capability enablement.** The capabilities that act on a business — formation, EIN, and registered agent — are enabled per account rather than on by default, because they file real records with government authorities. [Contact us](mailto:support@getpalm.com) and tell us about your use case. ## Next steps Form a business Register a new LLC or C-Corp with any US state. [Open](/comply/form-a-business) Apply for an EIN Get an EIN from the IRS, standalone or bundled with formation. [Open](/comply/apply-for-an-ein) Registered agent Provision the service, receive forwarded mail, and manage changes. [Open](/comply/registered-agent) Cases Respond to information requests Palm raises on a filing. [Open](/comply/cases) Webhooks Receive real-time status updates as filings progress. [Open](/developer-guide/webhooks) Filing API reference Full reference for the formation, EIN, and filing endpoints. [Open](/api-reference/v1/filing/list-filings) # Register in another state Source: https://docs.getpalm.com/comply/register-in-another-state Register an existing LLC in another US state, a filing known as foreign qualification. Palm handles the filing end to end. A business formed in one state that operates in another usually has to register there as a foreign entity, a filing known as foreign qualification. Palm reads the home-state details from the business record you already hold, prepares the target state's application, submits it, and returns the target-state registration number and documents when the state accepts the filing. Palm creates a new business record for the target-state registration at submission, so it is available for [monitoring](/monitor/overview) and [verification](/verify/verify-a-business). > [!WARNING] > > **Early access.** The foreign qualification endpoints are in preview and may change in backwards-incompatible ways before they are marked stable. [Contact us](mailto:support@getpalm.com) before building on them. *** ## How it works 1. Start from the home-state business. The business must already be in your Palm account, as registered in the state where it was formed. 2. Discover requirements. Ask what the target state needs, and what it costs. 3. Validate. Check the payload against the target state's rules before you commit to it. 4. Submit. Palm creates a filing and a new business record for the target-state registration. 5. Track. Follow the filing through its [lifecycle](/comply/overview#the-lifecycle), driven by webhooks. 6. Retrieve the result. Collect the target-state registration number and documents on completion. ## Start from the home-state business A foreign qualification request references an existing business by `business_id`. Palm reads the legal name, entity type, formation jurisdiction, formation date, and registration number from that record. If a field is missing, the request returns a `400` that lists the gap. The referenced record must be the registration in the state where the business was formed. Add a business that is not yet in your account through the [Business API](/api-reference/v1/business/add-a-business). ## Discover requirements Requirements differ between states, so read them rather than hardcoding a field list. ```bash Bash wrap theme={null} GET /v1/filing/foreign-qualification/requirement?entity_type=llc&jurisdiction=US-TX ``` The response carries: * **`schema`.** A JSON Schema for the request body in the target state: the common fields plus the fields that state requires. The fields Palm reads from the business record are absent, since you never supply them. * **`prerequisites`.** The documents the state needs alongside the application. Palm orders the home-state certificate of good standing or existence as part of the filing. * **`post_filing_obligations`.** What the registration starts once the state accepts it, such as a publication requirement. * **`expedited_tiers`.** The expedited processing tiers the state offers. * **`effective_date`.** Present only when the state offers a delayed effective date, with the state's own description of its limits. Build your collection flow from this response so you ask a member only for what the target state needs. See [Get foreign qualification requirements](/api-reference/v1/filing/get-foreign-qualification-requirements). Palm adds target states over time. A state that is not yet supported returns `501`. ### Price the filing To show a member a cost before they commit, call the [fee estimate endpoint](/api-reference/v1/filing/get-foreign-qualification-fee-estimate). Every figure returned before submission is an estimate. ```bash Bash wrap theme={null} GET /v1/filing/foreign-qualification/fee?entity_type=llc&jurisdiction=US-TX ``` Where the state offers expedited processing, omit `expedited_tier` to receive a priced menu of tiers, or pass one to fold its surcharge into the estimate. Pass your chosen tier as `expedited_tier` on the foreign qualification request. Where the state prices the filing on inputs you supply, a `400` lists any input that is missing. See [Fees and expedited processing](/comply/overview#fees-and-expedited-processing). ## Validate before you submit ```bash Bash wrap theme={null} POST /v1/filing/foreign-qualification/validate ``` Validation runs the same checks as the create endpoint, without creating a filing or a business record, and returns every finding in one pass: problems with the referenced business record, an expedited tier the state does not offer, and state compliance errors on the payload. It accepts a partial payload, which makes it usable for inline validation while a member is still filling in your form. > [!NOTE] > > Validation does not run the name check. The create endpoint can still reject a payload that passes validation when the legal name is not available in the target state. ## Submit the foreign qualification ```bash Bash wrap theme={null} POST /v1/filing/foreign-qualification ``` The request names the business and the target state, and carries only what the target state asks for beyond the business record: a filing contact, the business email, 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 requirements response lists. Palm validates the request against the business record and the target state's rules before it creates anything, and returns specific errors for anything that fails. A request for a business that already holds a registration in the target state returns `409 already_registered`, carrying the existing registration. On success, Palm creates: * A **filing** of type `foreign_qualification` in `queued` status. * A **new business record** for the target-state registration, whose `formation_jurisdiction` is the home state and `registration_jurisdiction` is the target state. The filing's `business_id` is the ID of this new record. Palm carries the owners of the referenced business over to the new record. Send an `Idempotency-Key` header and reuse it on every retry of the same submission, so a retry returns the original filing instead of creating a second one. Use `note` for context Palm operations should read before submitting, such as an existing name reservation. ### The name check Palm checks the legal name on every foreign qualification against the target state's naming rules and confirms it is available there. If the name does not clear, the request returns a `400` carrying the conflicts. If the state later declines the name, Palm opens a `legal_name_change` [case](/comply/cases) on the filing. ### Registered agent Omit the `registered_agent` block and Palm acts as registered agent in the target state. The registered agent appears under `related_items` on the filing. Pass the block to name your own agent there. See [Registered agent](/comply/registered-agent). ## Track the filing ```bash Bash wrap theme={null} GET /v1/filing/{filing_id} GET /v1/filing?type=foreign_qualification&business_id={id} ``` The filing moves through `ready_to_file`, `processing`, `filed`, and `completed`, and a `filing.*` webhook fires at each transition. If Palm needs something to finish the filing, it opens a [case](/comply/cases) and sends a `case.opened` webhook. Until the filing enters `processing`, you can cancel it with [Cancel a filing](/api-reference/v1/filing/cancel-a-filing). For what each status asks of you, see [the lifecycle](/comply/overview#the-lifecycle). ## Retrieve the result On `completed`, `filing.result` carries the target state's registration number, the date the state accepted the registration, and the Palm identifier of the new registration. ## Next steps Form a business Register a new LLC or C-Corp with any US state. [Open](/comply/form-a-business) Registered agent Provision the service, receive forwarded mail, and manage changes. [Open](/comply/registered-agent) Cases Respond to information requests Palm raises on a filing. [Open](/comply/cases) Register an existing business in another state Full reference for the foreign qualification endpoint. [Open](/api-reference/v1/filing/register-an-existing-business-in-another-state) # Registered agent Source: https://docs.getpalm.com/comply/registered-agent Provide registered agent service to your customers' businesses through Palm — at formation or after — and forward state mail through the same API. Every business registered with a US state must name a **registered agent**: the party the state sends legal and government documents to. Lawsuits, compliance notices, and tax correspondence all arrive there. The job has requirements most business owners cannot meet. The agent needs a physical street address in the state of registration, has to be available there during business hours, and that address goes on the public registry. A founder working from home, or from another state entirely, either publishes their home address or misses the mail. Missing it is expensive. A business with no valid agent can lose good standing, and the state treats mail sent to the address on file as delivered whether anyone read it or not. So most businesses hire an agent. Palm provides that service through established nationwide agent providers, and hands you the mail through the same API you already use. *** ## What Palm provides Palm acts as registered agent in all 50 US states and DC, for any business in your account, whether or not it was formed through Palm. Registered agent service is an add-on. Nothing else in Palm depends on it: Comply filings and Monitor work exactly the same for a business whose agent is someone else. ## How it works 1. Provide the service. Turn it on during formation, or move an existing business onto Palm. 2. Show your member the details. Read the agent name and address from the business. 3. Receive the mail. Documents arrive as webhooks with the file attached to the business. 4. Handle changes. Move a business onto Palm or off it as circumstances change. 5. End the service. Resign the agent when a business dissolves or offboards. ## Provide the service During a formation. Omit the `registered_agent` block from a [formation request](/comply/form-a-business#add-ons) and Palm designates an agent in the formation state, activating the service when the filing completes. Pass the block instead and Palm files the agent you name rather than providing one. For a business that already exists. Request a [change](#change-the-agent) and omit the `registered_agent` block. Palm provisions the service when the change completes. Either way, Palm assigns an agent per business. The provider entity and its address differ by state, so read them from the business itself rather than holding one set of details across your book. ```bash Bash wrap theme={null} GET /v1/business/{business_id}/registered-agent ``` The response tells you who the provider is, the status of the service, the state it covers, how long it has been running, and the agent name and address as filed with the state. A service is `pending` while provisioning is in flight, and `active` once Palm is the agent on record and mail is flowing. `termination_requested` means the service is winding down but still live. `terminated` means it has ended, and `failed` means provisioning could not complete. Asking for a business Palm has never served returns **404**, while a business whose service has ended returns **200** with `status: terminated`, so you can tell "never our agent" apart from "no longer our agent." ## What your member sees The agent of record is public. It sits on the state's registry, so you can show your member the name and address Palm returns for their business. Your member never has to deal with that agent. Everything the agent receives reaches you through the API, so you decide how and when it surfaces inside your product. ## Receive the mail When the state sends correspondence for a business Palm serves, Palm attaches a digital copy to the business and fires a `document.created` webhook. The event carries `resource_id`, the business the mail was addressed to, so you can route it on arrival. ```bash Bash wrap theme={null} GET /v1/document/{document_id} # metadata GET /v1/document/{document_id}/content # download the file ``` Every forwarded document stays on the business record with its own history, so you have a complete audit trail. Palm keeps forwarding for as long as it is the agent, including while a termination is still in flight. ### What arrives The document's `type` identifies what came in. | Type | Description | | - | - | | `service_of_process` | Legal service — a summons, complaint, or subpoena. | | `notice` | A notice from a government authority, such as a state compliance reminder or an annual-report deadline. | | `mail` | Forwarded correspondence with no more specific classification. | Agent operations produce documents of their own: `ra_change_confirmation`, `ra_resignation`, and `receipt`. Filing artifacts the state issues — `certificate_of_formation`, `ein_letter`, `filing_confirmation`, `welcome_letter` — arrive the same way. ## Change the agent Businesses switch agents. A member consolidates providers, moves their company, or brings the work in house. The same call handles both directions. ```bash Bash wrap theme={null} PATCH /v1/business/{business_id}/registered-agent ``` Send `status: change_requested`. Supply a `registered_agent` block to name the agent you are moving to, or omit it to move the business onto Palm. A business has an agent in every state where it is registered, and each registration is its own business record, so Palm files the change in the record's `registration_jurisdiction`. A change on a business with no `registration_jurisdiction` is rejected with a `400`. Where a state requires a filing to make the change, Palm handles it without you having to submit one. The service goes `pending` while the change is in flight, then lands one of three ways. Moving onto Palm fires `registered_agent.activated` and the service becomes `active`. Moving away fires `registered_agent.changed` and the service ends. If the change cannot complete, `registered_agent.change_failed` fires with a `rejection_reason` and the service reverts to the status it held before the request, so the business is never left without its agent of record. Resolve the reason and submit again. ## End the service When a business dissolves or offboards and no change filing is involved, ask Palm to resign. ```bash Bash wrap theme={null} PATCH /v1/business/{business_id}/registered-agent ``` Send `status: termination_requested` with a reason. Palm handles the state resignation, including the successor-agent step in the states that require one, and keeps forwarding mail until the resignation is accepted. On acceptance the service becomes `terminated` and `registered_agent.terminated` fires. If the state refuses, `registered_agent.termination_failed` fires with a `rejection_reason` and the service stays `active`. Palm runs one registered agent operation at a time, so it rejects a second request while a change or termination is in flight. > [!NOTE] > > In [test mode](/get-started/test-mode) both actions complete immediately, so you can exercise the whole path without waiting on a state. ## Webhooks Registered agent events cover activation, change, and termination, with a failure event for each, plus `document.created` for forwarded mail. See [Webhooks](/developer-guide/webhooks) for the full list, payloads, delivery, and signature verification. ## Next steps Form a business Bundle registered agent service with a formation. [Open](/comply/form-a-business) Comply overview How filings, cases, and documents fit together. [Open](/comply/overview) Monitor overview Track standing and deadline changes on a business. [Open](/monitor/overview) Registered agent reference Full reference for the registered agent endpoints. [Open](/api-reference/v1/registered-agent/retrieve-registered-agent-service) # Webhook example payloads Source: https://docs.getpalm.com/developer-guide/webhook-example-payloads A complete, realistic example payload for every Palm webhook event type. A concrete payload for every webhook event Palm delivers. Every payload shares the same envelope — `id`, `object: "event"`, `type`, `created_at`, and an event-specific `data` object. For the concepts (setup, signing, retries, idempotency), see the [Webhooks overview](/developer-guide/webhooks). ## Verification events ### user.verification.completed *Fires when a user verification finishes.* This example is a flagged applicant (`risk.level: high`), so `risk.reasons`, mismatched `match` values, and a watchlist hit are all populated. On a clean pass, `reasons` and `matches` are empty and `match` values are all `match`. ```json JSON wrap theme={null} { "id": "evt_1718296200000_f6g7h8i9j0k1", "object": "event", "type": "user.verification.completed", "mode": "live", "created_at": "2026-06-13T16:30:00Z", "data": { "object": { "user_id": "a1d4f9c2-8b3e-4e6a-9c1d-7f2b5a8e0c43", "verification_id": "c7e2b9a4-1f6d-4a3c-8e9b-2d5f0a7c4b16", "reference_id": "your_user_ref_5573", "status": "completed", "risk": { "level": "high", "reasons": [ "Address mismatch detected", "High velocity on phone number (5 applications in 24 hours)", "Synthetic identity indicators detected with 72% confidence", "Potential PEP match on Dow Jones watchlist" ] }, "match": { "first_name": "match", "last_name": "match", "middle_name": "not_checked", "date_of_birth": "match", "ssn": "partial_match", "email": "match", "phone_number": "match", "address_line_1": "no_match", "address_line_2": "not_checked", "city": "no_match", "region": "match", "postal_code": "no_match" }, "synthetic": { "is_synthetic": true, "confidence_score": 72, "indicators": [ "SSN issued after applicant date of birth", "Credit file recently established" ] }, "velocity": { "email": 1, "phone": 5, "ssn": 2, "address": 3 }, "device": { "risk_score": 68, "is_emulator": false, "is_vpn": true, "is_proxy": false }, "watchlist": { "status": "potential_match", "matches": [ { "type": "pep", "name": "dow_jones_pep", "confidence_score": 63 } ] }, "created_at": "2026-06-13T16:28:42Z", "updated_at": "2026-06-13T16:30:00Z" } } } ``` ### business.verification.completed *Fires when a business verification finishes.* Includes the full user-verification result for each associate. This example is a critical-risk outcome: the EIN does not match IRS records, the business is no longer in good standing, and an associate failed verification. ```json JSON wrap theme={null} { "id": "evt_1718296500000_a1b2c3d4e5f6", "object": "event", "type": "business.verification.completed", "mode": "live", "created_at": "2026-06-13T16:35:00Z", "data": { "object": { "business_id": "e4b9c1a7-3d2f-4a8e-9b6c-1f0d5a7e2c83", "verification_id": "f2a7d4e9-6b1c-4f3a-8d5e-9c0b3a6f1d27", "reference_id": "your_business_ref_3391", "status": "completed", "risk": { "level": "critical", "reasons": [ "EIN does not match IRS records for the provided legal name", "Business is not in good standing: status is dissolved in the formation jurisdiction (Delaware)" ] }, "match": { "legal_name": "match", "ein": "no_match", "entity_type": "match", "registration_jurisdiction": "match", "formation_jurisdiction": "match", "formation_date": "match", "address_line_1": "match", "address_line_2": "not_checked", "city": "match", "region": "match", "postal_code": "match" }, "associates": [ { "user_id": "b8c3e6f1-9a2d-4c7e-8b5f-3a1d6e9c0f24", "verification_id": "d1f4a7c2-5e8b-4a9d-9c3e-6f2b0a5d8e13", "reference_id": "owner_1", "status": "completed", "risk": { "level": "high", "reasons": [ "SSN does not match the provided name", "Identity could not be verified against authoritative records" ] }, "match": { "first_name": "match", "last_name": "match", "middle_name": "not_checked", "date_of_birth": "no_match", "ssn": "no_match", "email": "match", "phone_number": "match", "address_line_1": "no_match", "address_line_2": "not_checked", "city": "match", "region": "match", "postal_code": "no_match" }, "watchlist": { "status": "potential_match", "matches": [ { "type": "adverse_media", "name": "complyadvantage_media", "confidence_score": 57 } ] } } ] } } } ``` ## Monitoring events ### business.registration.updated *Fires when Palm detects a change to a monitored business in the authoritative record.* `data.business` is a lightweight reference; `data.changes` carries one entry per field that moved. Values mirror the source record (typically uppercase). ```json JSON wrap theme={null} { "id": "evt_1718447400000_h8i9j0k1l2m3", "object": "event", "type": "business.registration.updated", "mode": "live", "created_at": "2026-06-15T10:30:00Z", "data": { "business": { "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "palm_id": "1234-5678-9012", "legal_name": "ACME HOLDINGS LLC", "registration_jurisdiction_id": "US-NC" }, "changes": [ { "attribute": "address.principal", "action": "updated", "summary": "Principal address changed from 150 FAYETTEVILLE ST, RALEIGH, NC to 401 S TRYON ST, CHARLOTTE, NC", "previous_value": { "street_line_1": "150 FAYETTEVILLE ST", "street_line_2": "SUITE 1100", "city": "RALEIGH", "region": "NC", "postal_code": "27601", "country": "US" }, "current_value": { "street_line_1": "401 S TRYON ST", "street_line_2": "SUITE 2200", "city": "CHARLOTTE", "region": "NC", "postal_code": "28202", "country": "US" } }, { "attribute": "name.dba", "action": "added", "summary": "Assumed business name added: ACME LOGISTICS", "previous_value": null, "current_value": "ACME LOGISTICS" } ] } } ``` ### business.filing.due *Fires when a compliance filing deadline is approaching.* ```json JSON wrap theme={null} { "id": "evt_1740571200000_l2m3n4o5p6q7", "object": "event", "type": "business.filing.due", "mode": "live", "created_at": "2026-02-26T12:00:00Z", "data": { "object": { "type": { "id": "annual_report", "name": "Annual Report" }, "frequency": "annual", "due_date": "2026-04-15" }, "business": { "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "palm_id": "1234-5678-9012", "legal_name": "ACME HOLDINGS LLC", "registration_jurisdiction_id": "US-NC" } } } ``` ### business.filing.overdue *Fires when a compliance filing deadline has passed.* Identical structure to `business.filing.due`; only the event `type` differs. ```json JSON wrap theme={null} { "id": "evt_1744761600000_m3n4o5p6q7r8", "object": "event", "type": "business.filing.overdue", "mode": "live", "created_at": "2026-04-16T12:00:00Z", "data": { "object": { "type": { "id": "annual_report", "name": "Annual Report" }, "frequency": "annual", "due_date": "2026-04-15" }, "business": { "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "palm_id": "1234-5678-9012", "legal_name": "ACME HOLDINGS LLC", "registration_jurisdiction_id": "US-NC" } } } ``` ## Filing events All `filing.*` events carry the same `filing` object on `data.object`. Across the lifecycle only `status` changes; `result`, `documents`, and `fee` populate on completion. Route on `data.object.type` (`formation`, `ein`). A formation bundles its obligations under `related_items` — each with its own `object`, `id`, and `status`. The registered agent is one such item and is **not** a filing: it never emits `filing.*` events, only its own `registered_agent.*` events (see below). ### filing.queued *Fires when a filing is received and validated (preparing for submission).* `result` and `fee` are `null` and no documents exist yet. ```json JSON wrap theme={null} { "id": "evt_1718269200000_a1b2c3d4e5f6", "object": "event", "type": "filing.queued", "mode": "live", "created_at": "2026-06-13T09:15:00Z", "data": { "object": { "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e", "object": "filing", "type": "formation", "status": "queued", "entity_type": "llc", "jurisdiction": "US-NC", "name": "Acme Holdings LLC", "expedited_tier": "same_day", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "result": null, "parent_filing_id": null, "related_items": [ { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "queued" }, { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "pending" } ], "documents": [], "fee": null, "status_reason": null, "canceled_by": null, "canceled_at": null, "cases": [], "metadata": {}, "created_at": "2026-06-13T09:15:00Z", "updated_at": "2026-06-13T09:15:00Z" } } } ``` ### filing.ready\_to\_file *Fires when Palm is ready to submit the filing to the authority.* ```json JSON wrap theme={null} { "id": "evt_1718290800000_b2c3d4e5f6a7", "object": "event", "type": "filing.ready_to_file", "mode": "live", "created_at": "2026-06-13T15:00:00Z", "data": { "object": { "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e", "object": "filing", "type": "formation", "status": "ready_to_file", "entity_type": "llc", "jurisdiction": "US-NC", "name": "Acme Holdings LLC", "expedited_tier": "same_day", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "result": null, "parent_filing_id": null, "related_items": [ { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "queued" }, { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "pending" } ], "documents": [], "fee": null, "status_reason": null, "canceled_by": null, "canceled_at": null, "cases": [], "metadata": {}, "created_at": "2026-06-13T09:15:00Z", "updated_at": "2026-06-13T15:00:00Z" } } } ``` ### filing.processing *Fires when Palm has submitted the filing and the authority is processing it.* ```json JSON wrap theme={null} { "id": "evt_1718369940000_c3d4e5f6a7b8", "object": "event", "type": "filing.processing", "mode": "live", "created_at": "2026-06-14T13:00:00Z", "data": { "object": { "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e", "object": "filing", "type": "formation", "status": "processing", "entity_type": "llc", "jurisdiction": "US-NC", "name": "Acme Holdings LLC", "expedited_tier": "same_day", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "result": null, "parent_filing_id": null, "related_items": [ { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "queued" }, { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "pending" } ], "documents": [], "fee": null, "status_reason": null, "canceled_by": null, "canceled_at": null, "cases": [], "metadata": {}, "created_at": "2026-06-13T09:15:00Z", "updated_at": "2026-06-14T13:00:00Z" } } } ``` ### filing.filed *Fires when the authority has accepted the filing; final confirmation is pending.* ```json JSON wrap theme={null} { "id": "evt_1718373600000_d4e5f6a7b8c9", "object": "event", "type": "filing.filed", "mode": "live", "created_at": "2026-06-14T14:00:00Z", "data": { "object": { "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e", "object": "filing", "type": "formation", "status": "filed", "entity_type": "llc", "jurisdiction": "US-NC", "name": "Acme Holdings LLC", "expedited_tier": "same_day", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "result": null, "parent_filing_id": null, "related_items": [ { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "queued" }, { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "pending" } ], "documents": [], "fee": null, "status_reason": null, "canceled_by": null, "canceled_at": null, "cases": [], "metadata": {}, "created_at": "2026-06-13T09:15:00Z", "updated_at": "2026-06-14T14:00:00Z" } } } ``` ### filing.completed (formation) *Fires when the filing is done and the result is available.* For a formation, `result` holds the registration number and formation date, the certificate appears under `documents`, and `fee` carries the finalized breakdown (including `total`). ```json JSON wrap theme={null} { "id": "evt_1718372400000_n4o5p6q7r8s9", "object": "event", "type": "filing.completed", "mode": "live", "created_at": "2026-06-14T14:30:00Z", "data": { "object": { "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e", "object": "filing", "type": "formation", "status": "completed", "entity_type": "llc", "jurisdiction": "US-NC", "name": "Acme Holdings LLC", "expedited_tier": "same_day", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "result": { "registration_number": "NC-12345678", "formation_date": "2026-06-14" }, "parent_filing_id": null, "related_items": [ { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "ready_to_file" }, { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "active" } ], "documents": [ { "id": "3e7b1a9c-5d2f-4e8a-9b6c-1d4f7a0e3b2c", "object": "document", "type": "certificate_of_formation", "uploaded_at": "2026-06-14T14:29:51Z" }, { "id": "9f4c2e8d-7b1a-4f6e-a3d5-8c0b2e5f1a7d", "object": "document", "type": "filing_confirmation", "uploaded_at": "2026-06-14T14:29:52Z" }, { "id": "c1a7d3f9-4e2b-4a8c-9f5d-3b6e0c8a2d4f", "object": "document", "type": "receipt", "uploaded_at": "2026-06-14T14:29:53Z" } ], "fee": { "base": { "amount": 125, "currency": "USD" }, "dynamic": { "amount": 100, "currency": "USD" }, "total": { "amount": 225, "currency": "USD" }, "items": [ { "component_type": "base", "name": "filing", "amount": 125, "currency": "USD" }, { "component_type": "dynamic", "name": "expedited", "amount": 100, "currency": "USD" } ] }, "status_reason": null, "canceled_by": null, "canceled_at": null, "cases": [], "metadata": {}, "created_at": "2026-06-13T09:15:00Z", "updated_at": "2026-06-14T14:30:00Z" } } } ``` ### filing.completed (EIN) *Same `filing.completed` event for an EIN filing* — a different `type` and `result` (issued EIN and entity name), no state fee, and the bundled child of the formation above (`parent_filing_id` points back to it). ```json JSON wrap theme={null} { "id": "evt_1718373300000_c4d5e6f7a8b9", "object": "event", "type": "filing.completed", "mode": "live", "created_at": "2026-06-14T15:05:00Z", "data": { "object": { "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "object": "filing", "type": "ein", "status": "completed", "entity_type": "llc", "jurisdiction": null, "name": "Acme Holdings LLC", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "result": { "ein_number": "12-3456789", "entity_name": "Acme Holdings LLC" }, "parent_filing_id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e", "related_items": [], "documents": [ { "id": "8c2d1f6b-3a9e-4d7c-b5f2-0a4e7c1d9b3f", "object": "document", "type": "ein_letter", "uploaded_at": "2026-06-14T15:04:40Z" } ], "fee": null, "status_reason": null, "canceled_by": null, "canceled_at": null, "cases": [], "metadata": {}, "created_at": "2026-06-13T09:15:30Z", "updated_at": "2026-06-14T15:05:00Z" } } } ``` ### filing.canceled *Fires when a filing is canceled.* `status_reason`, `canceled_by`, and `canceled_at` are populated. ```json JSON wrap theme={null} { "id": "evt_1718373000000_b2c3d4e5f6a7", "object": "event", "type": "filing.canceled", "mode": "live", "created_at": "2026-06-14T14:40:00Z", "data": { "object": { "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e", "object": "filing", "type": "formation", "status": "canceled", "entity_type": "llc", "jurisdiction": "US-NC", "name": "Acme Holdings LLC", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "result": null, "fee": null, "status_reason": "Canceled at partner request before submission to the state.", "canceled_by": "partner", "canceled_at": "2026-06-14T14:40:00Z", "cases": [], "metadata": {}, "created_at": "2026-06-13T09:15:00Z", "updated_at": "2026-06-14T14:40:00Z" } } } ``` ## Case events All `case.*` events carry the same `case` object on `data.object`; `status`, `response`, `resolved_at`, and `resolution_reason` evolve as the case progresses. `request.documents` holds the ids of files Palm sent you, and `response.documents` the ids of files you sent back. ### case.opened (missing\_information) *Fires when Palm opens a case and needs your response.* For `missing_information` cases, `request.fields` describes exactly what to supply. An entry typed `document` is answered with the id of a file uploaded to the business. ```json JSON wrap theme={null} { "id": "evt_1718373600000_c3d4e5f6a7b8", "object": "event", "type": "case.opened", "mode": "live", "created_at": "2026-06-14T14:50:00Z", "data": { "object": { "id": "4f8c2b1e-7d9a-4c3e-8b1f-2a6d9c0e4b7a", "object": "case", "parent_type": "filing", "parent_id": "c8a1f5d3-9b26-4e74-a0f1-6d38b7e2c495", "kind": "missing_information", "status": "needs_response", "summary": "The state needs the name reservation certificate before it will accept this filing.", "details": "North Carolina holds a reservation on \"Brightwater Labs LLC\" and will not accept the articles without the certificate. The state's rejection is attached. Send the reservation number and a copy of the certificate.", "request": { "fields": [ { "name": "name_reservation_number", "type": "string", "description": "The reservation number the state issued when the name was reserved.", "required": true, "example": "NR-2026-0041872" }, { "name": "name_reservation_certificate", "type": "document", "description": "A copy of the certificate the state issued for the reserved name.", "required": true, "document_types": ["other"] } ], "documents": ["a1e7d4c9-5b23-4f81-9e06-3c8b2d7a5f14"] }, "response": null, "due_at": "2026-06-21T23:59:59Z", "opened_at": "2026-06-14T14:50:00Z", "resolved_at": null, "resolution_reason": null, "metadata": {}, "created_at": "2026-06-14T14:50:00Z", "updated_at": "2026-06-14T14:50:00Z" } } } ``` ### case.updated *Fires when an open case changes* — for example, your response is received and the case moves to `under_review`. `response.fields` now carries what you submitted. ```json JSON wrap theme={null} { "id": "evt_1718442000000_e5f6a7b8c9d0", "object": "event", "type": "case.updated", "mode": "live", "created_at": "2026-06-15T09:00:00Z", "data": { "object": { "id": "4f8c2b1e-7d9a-4c3e-8b1f-2a6d9c0e4b7a", "object": "case", "parent_type": "filing", "parent_id": "c8a1f5d3-9b26-4e74-a0f1-6d38b7e2c495", "kind": "missing_information", "status": "under_review", "summary": "The state needs the name reservation certificate before it will accept this filing.", "details": "North Carolina holds a reservation on \"Brightwater Labs LLC\" and will not accept the articles without the certificate. The state's rejection is attached. Send the reservation number and a copy of the certificate.", "request": { "fields": [ { "name": "name_reservation_number", "type": "string", "description": "The reservation number the state issued when the name was reserved.", "required": true, "example": "NR-2026-0041872" }, { "name": "name_reservation_certificate", "type": "document", "description": "A copy of the certificate the state issued for the reserved name.", "required": true, "document_types": ["other"] } ], "documents": ["a1e7d4c9-5b23-4f81-9e06-3c8b2d7a5f14"] }, "response": { "fields": { "name_reservation_number": "NR-2026-0041872", "name_reservation_certificate": "3b6f9d21-8c47-4e50-a9d3-1f2e7b4c8a06" }, "documents": ["c5d8a2f7-4e91-4b63-8f10-9a7c3e5d2b48"] }, "due_at": "2026-06-21T23:59:59Z", "opened_at": "2026-06-14T14:50:00Z", "resolved_at": null, "resolution_reason": null, "metadata": {}, "created_at": "2026-06-14T14:50:00Z", "updated_at": "2026-06-15T09:00:00Z" } } } ``` ### case.resolved *Fires when the case closes* (`resolved` or `superseded`). `resolved_at` is set and `resolution_reason` is one of `response_received`, `no_response_needed`, `parent_canceled`, `parent_completed`, or `parent_failed`. ```json JSON wrap theme={null} { "id": "evt_1718447400000_d5e6f7a8b9c0", "object": "event", "type": "case.resolved", "mode": "live", "created_at": "2026-06-15T11:00:00Z", "data": { "object": { "id": "4f8c2b1e-7d9a-4c3e-8b1f-2a6d9c0e4b7a", "object": "case", "parent_type": "filing", "parent_id": "c8a1f5d3-9b26-4e74-a0f1-6d38b7e2c495", "kind": "missing_information", "status": "resolved", "summary": "The state needs the name reservation certificate before it will accept this filing.", "details": "North Carolina holds a reservation on \"Brightwater Labs LLC\" and will not accept the articles without the certificate. The state's rejection is attached. Send the reservation number and a copy of the certificate.", "request": { "fields": [ { "name": "name_reservation_number", "type": "string", "description": "The reservation number the state issued when the name was reserved.", "required": true, "example": "NR-2026-0041872" }, { "name": "name_reservation_certificate", "type": "document", "description": "A copy of the certificate the state issued for the reserved name.", "required": true, "document_types": ["other"] } ], "documents": ["a1e7d4c9-5b23-4f81-9e06-3c8b2d7a5f14"] }, "response": { "fields": { "name_reservation_number": "NR-2026-0041872", "name_reservation_certificate": "3b6f9d21-8c47-4e50-a9d3-1f2e7b4c8a06" }, "documents": ["c5d8a2f7-4e91-4b63-8f10-9a7c3e5d2b48"] }, "due_at": "2026-06-21T23:59:59Z", "opened_at": "2026-06-14T14:50:00Z", "resolved_at": "2026-06-15T11:00:00Z", "resolution_reason": "response_received", "metadata": {}, "created_at": "2026-06-14T14:50:00Z", "updated_at": "2026-06-15T11:00:00Z" } } } ``` ### case.opened (legal\_name\_change) *Fires when the state will not accept the name on the filing.* This kind asks for exactly one required `string` field named `legal_name` and nothing else. Resolving it renames the filing, any bundled filing not yet submitted, and the business record. ```json JSON wrap theme={null} { "id": "evt_1718373900000_a9b0c1d2e3f4", "object": "event", "type": "case.opened", "mode": "live", "created_at": "2026-06-13T10:20:00Z", "data": { "object": { "id": "9b3e7a1c-6d28-4f50-b9a7-4c1e8d2f6b03", "object": "case", "parent_type": "filing", "parent_id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e", "kind": "legal_name_change", "status": "needs_response", "summary": "The state will not accept the name on this filing.", "details": "North Carolina rejected \"Acme LLC\" as too close to an entity already on the register. Send a different name and Palm will refile.", "request": { "fields": [ { "name": "legal_name", "type": "string", "description": "A different business name to file under.", "required": true, "example": "Acme Holdings LLC" } ] }, "response": null, "due_at": "2026-06-20T23:59:59Z", "opened_at": "2026-06-13T10:20:00Z", "resolved_at": null, "resolution_reason": null, "metadata": {}, "created_at": "2026-06-13T10:20:00Z", "updated_at": "2026-06-13T10:20:00Z" } } } ``` ## Platform events Platform events deliver the full resource object. PII stays in the vault, so payloads expose only fingerprints and non-encrypted cached vault fields. ### user.created *Fires when a person is created through the API.* ```json JSON wrap theme={null} { "id": "evt_1718290000000_d4e5f6a7b8c9", "object": "event", "type": "user.created", "mode": "live", "created_at": "2026-06-13T14:46:40Z", "data": { "object": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "object": "user", "status": "active", "display_name": "John Doe", "email_fingerprint": "f7c3bc1d808e04732adf679965ccc34ca7ae3441", "phone_fingerprint": "a8d4bc2e919f15843be0890076ddd45db8bf4552", "verification": null, "vault": { "identity.first_name": "John", "identity.last_name": "Doe" }, "metadata": { "external_id": "user_4821" }, "created_at": "2026-06-13T14:46:40Z", "updated_at": "2026-06-13T14:46:40Z" } } } ``` ### user.removed *Fires when a person is removed.* Same object as `user.created` with `status: deleted`. ```json JSON wrap theme={null} { "id": "evt_1719828000000_f6a7b8c9d0e1", "object": "event", "type": "user.removed", "mode": "live", "created_at": "2026-07-01T10:00:00Z", "data": { "object": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "object": "user", "status": "deleted", "display_name": "John Doe", "email_fingerprint": "f7c3bc1d808e04732adf679965ccc34ca7ae3441", "phone_fingerprint": "a8d4bc2e919f15843be0890076ddd45db8bf4552", "verification": null, "vault": { "identity.first_name": "John", "identity.last_name": "Doe" }, "metadata": { "external_id": "user_4821" }, "created_at": "2026-06-13T14:46:40Z", "updated_at": "2026-07-01T10:00:00Z" } } } ``` ### business.created *Fires when a business is created through the API.* This is the canonical business object — the same shape returned by `GET /business/{id}`. The EIN is encrypted (surfaced only via `ein_fingerprint`); the non-encrypted fields you set are echoed under `vault` by field ID. ```json JSON wrap theme={null} { "id": "evt_1718269140000_e1f2a3b4c5d6", "object": "event", "type": "business.created", "mode": "live", "created_at": "2026-06-13T09:14:00Z", "data": { "object": { "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "object": "business", "status": "active", "palm_id": "1234-5678-9012", "display_name": "Acme Holdings LLC", "ein_fingerprint": "9b1c4f7a2e8d05c3a6f9b2e4d7c1a0e3f5b8d2c6", "verification": null, "vault": { "business.legal_name": "Acme Holdings LLC", "business.dba_name": "Acme Logistics", "business.entity_type": "llc", "business.formation_date": "2020-05-15", "business.formation_jurisdiction": "US-DE", "business.registration_jurisdiction": "US-NC", "business.address_line_1": "401 S Tryon St", "business.address_line_2": "Suite 2200", "business.city": "Charlotte", "business.region": "NC", "business.postal_code": "28202", "business.country": "US", "business.phone_number": "+17045551234", "business.email": "ops@acmeholdings.com", "business.website": "https://acmeholdings.com", "business.naics_code": "541614" }, "metadata": { "external_id": "biz_4821", "customer_tier": "premium", "account_manager": "jordan.lee" }, "created_at": "2026-06-13T09:14:00Z", "updated_at": "2026-06-13T09:14:00Z" } } } ``` Field notes: * **`ein_fingerprint`** — SHA-256 fingerprint of the EIN, for duplicate detection and search without exposing the value. `business.ein` is encrypted and is not echoed in `vault`. * **`palm_id`** — Palm's identifier for the business; `null` until the business is matched to a registry record. * **`verification`** — `null` until the business is verified, then a summary: `{ "id": "...", "risk_level": "low", "workflow": { "name": "Business Verification", "version": 1 }, "executed_at": "..." }`. The full result arrives on `business.verification.completed`. * **`vault`** — cached non-encrypted business fields you supplied, keyed by field ID. Valid keys: `business.legal_name`, `business.dba_name`, `business.entity_type`, `business.formation_date`, `business.formation_jurisdiction`, `business.registration_jurisdiction`, `business.address_line_1`, `business.address_line_2`, `business.city`, `business.region`, `business.postal_code`, `business.country`, `business.phone_number`, `business.email`, `business.website`, `business.naics_code`. * **`metadata`** — up to 50 of your own key-value pairs, returned on every event for this business. ### business.removed *Fires when a business is removed.* Same object as `business.created` with `status: deleted`. ```json JSON wrap theme={null} { "id": "evt_1719828000000_a7b8c9d0e1f2", "object": "event", "type": "business.removed", "mode": "live", "created_at": "2026-07-01T10:00:00Z", "data": { "object": { "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "object": "business", "status": "deleted", "palm_id": "1234-5678-9012", "display_name": "Acme Holdings LLC", "ein_fingerprint": "9b1c4f7a2e8d05c3a6f9b2e4d7c1a0e3f5b8d2c6", "verification": null, "vault": { "business.legal_name": "Acme Holdings LLC", "business.entity_type": "llc", "business.region": "NC" }, "metadata": { "external_id": "biz_4821" }, "created_at": "2026-06-13T09:14:00Z", "updated_at": "2026-07-01T10:00:00Z" } } } ``` ## Document events ### document.created (filing artifact) *Fires when Palm attaches a document on its own initiative.* Route on `data.object.type`. Here, the certificate produced by a completed formation. `resource_type` and `resource_id` name the owner, so you can route the document without a follow-up call. ```json JSON wrap theme={null} { "id": "evt_1718372460000_f6a7b8c9d0e1", "object": "event", "type": "document.created", "mode": "live", "created_at": "2026-06-14T14:30:51Z", "data": { "object": { "id": "3e7b1a9c-5d2f-4e8a-9b6c-1d4f7a0e3b2c", "object": "document", "resource_type": "business", "resource_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "type": "certificate_of_formation", "filename": "certificate_of_formation.pdf", "file_size": 184320, "content_type": "application/pdf", "status": "verified", "upload_date": "2026-06-14T14:30:51Z", "metadata": {}, "created_at": "2026-06-14T14:30:51Z", "updated_at": "2026-06-14T14:30:51Z" } } } ``` ### document.created (forwarded mail) *The same event for forwarded registered-agent mail.* Here `service_of_process`, legal service delivered to the agent address. See [Document types](/developer-guide/webhooks#document-types) for the full list. `resource_id` is the business the mail was addressed to. ```json JSON wrap theme={null} { "id": "evt_1723723200000_b8c9d0e1f2a3", "object": "event", "type": "document.created", "mode": "live", "created_at": "2026-08-15T12:00:00Z", "data": { "object": { "id": "2b7f9d1c-4e6a-4b8d-9f3c-5a0e2d7c1b48", "object": "document", "resource_type": "business", "resource_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "type": "service_of_process", "filename": "summons_2026-08-15.pdf", "file_size": 98304, "content_type": "application/pdf", "status": "verified", "upload_date": "2026-08-15T12:00:00Z", "metadata": {}, "created_at": "2026-08-15T12:00:00Z", "updated_at": "2026-08-15T12:00:00Z" } } } ``` ## Registered agent events Registered agent (RA) is a **standalone resource**, not a filing — it never emits `filing.*` events. On a formation it appears in `related_items` as a `registered_agent` item (status `pending` until it goes `active`), and it has its own resource at `GET /v1/business/:business_id/registered-agent`. Every lifecycle transition delivers the RA snapshot on `data.object`: * **`status`** — `pending`, `active`, `termination_requested`, `terminated`, or `failed`. * **`provider`** — `palm` while Palm is the agent (`active` / `termination_requested`), `external` after a change-away or termination. * **`rejection_reason`** — present only on the failure events (`failed`, `change_failed`, `termination_failed`). RA payloads do not carry the agent's `name` or `address`; the concrete provider Palm uses is server-side and never exposed. ### registered\_agent.activated *Fires when Palm becomes the registered agent* — formation provisioning completing, or a change into Palm. `status` is `active`, `provider` is `palm`. ```json JSON wrap theme={null} { "id": "evt_1718372700000_a7b8c9d0e1f2", "object": "event", "type": "registered_agent.activated", "mode": "live", "created_at": "2026-06-14T14:35:00Z", "data": { "object": { "object": "registered_agent", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "provider": "palm", "status": "active", "jurisdiction": "NC", "started_at": "2026-06-14T14:35:00Z", "ended_at": null } } } ``` ### registered\_agent.failed *Fires when RA provisioning (or a required state submission) fails* on the assignment path — there was no prior RA to fall back to. `status` is `failed` and `rejection_reason` explains the blocker. ```json JSON wrap theme={null} { "id": "evt_1718373900000_b1c2d3e4f5a6", "object": "event", "type": "registered_agent.failed", "mode": "live", "created_at": "2026-06-14T15:15:00Z", "data": { "object": { "object": "registered_agent", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "provider": "palm", "status": "failed", "jurisdiction": "NC", "started_at": null, "ended_at": null, "rejection_reason": "Registered-agent provisioning could not be completed: the state rejected the agent designation." } } } ``` ### registered\_agent.change\_failed *Fires when a partner-requested RA change cannot be completed.* Unlike an assignment failure, the change never took effect, so `status` reverts from the transient `pending` back to `active` — Palm remains the RA of record. `rejection_reason` explains the blocker. ```json JSON wrap theme={null} { "id": "evt_1723456800000_c2d3e4f5a6b7", "object": "event", "type": "registered_agent.change_failed", "mode": "live", "created_at": "2026-08-12T09:00:00Z", "data": { "object": { "object": "registered_agent", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "provider": "palm", "status": "active", "jurisdiction": "NC", "started_at": "2026-06-14T14:35:00Z", "ended_at": null, "rejection_reason": "Registered-agent change could not be completed: the destination agent did not confirm consent. Palm remains the registered agent." } } } ``` ### registered\_agent.changed *Fires when an RA change moves the business to another provider.* `provider` becomes `external`, `status` is `terminated`, and `ended_at` is set. ```json JSON wrap theme={null} { "id": "evt_1725192000000_e1f2a3b4c5d6", "object": "event", "type": "registered_agent.changed", "mode": "live", "created_at": "2026-09-01T12:00:00Z", "data": { "object": { "object": "registered_agent", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "provider": "external", "status": "terminated", "jurisdiction": "NC", "started_at": "2026-06-14T14:35:00Z", "ended_at": "2026-09-01T12:00:00Z" } } } ``` ### registered\_agent.termination\_requested *Fires when you ask Palm to resign* via `PATCH /v1/business/:business_id/registered-agent`. `status` moves to `termination_requested`; Palm stays the RA on file and keeps forwarding mail until operations completes the work. ```json JSON wrap theme={null} { "id": "evt_1723111200000_c9d0e1f2a3b4", "object": "event", "type": "registered_agent.termination_requested", "mode": "live", "created_at": "2026-08-20T10:00:00Z", "data": { "object": { "object": "registered_agent", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "provider": "palm", "status": "termination_requested", "jurisdiction": "NC", "started_at": "2026-06-14T14:35:00Z", "ended_at": null } } } ``` ### registered\_agent.terminated *Fires when operations completes the termination and Palm is no longer the RA on file.* `status` is `terminated`, `provider` flips to `external`, and `ended_at` carries the close timestamp. ```json JSON wrap theme={null} { "id": "evt_1725192000000_b9c0d1e2f3a4", "object": "event", "type": "registered_agent.terminated", "mode": "live", "created_at": "2026-09-01T12:00:00Z", "data": { "object": { "object": "registered_agent", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "provider": "external", "status": "terminated", "jurisdiction": "NC", "started_at": "2026-06-14T14:35:00Z", "ended_at": "2026-09-01T12:00:00Z" } } } ``` ### registered\_agent.termination\_failed *Fires when a termination cannot be completed* (state refused the resignation, a successor RA is required and none was supplied, etc.). `status` reverts to `active`, `rejection_reason` explains the blocker, and Palm keeps serving as RA. You can re-submit once it is resolved. ```json JSON wrap theme={null} { "id": "evt_1724594400000_d0e1f2a3b4c5", "object": "event", "type": "registered_agent.termination_failed", "mode": "live", "created_at": "2026-08-25T14:00:00Z", "data": { "object": { "object": "registered_agent", "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "provider": "palm", "status": "active", "jurisdiction": "NC", "started_at": "2026-06-14T14:35:00Z", "ended_at": null, "rejection_reason": "State refused resignation form: a successor registered agent must be designated before Palm can resign." } } } ``` # Webhooks overview Source: https://docs.getpalm.com/developer-guide/webhooks Receive real-time notifications when events occur across Verify, Monitor, and Comply. Instead of polling the API for changes, register an endpoint and Palm pushes events to you. Webhooks deliver events from all Palm products through a single integration — verification results, monitoring alerts, and compliance updates all arrive at the same endpoint. ![Image showcasing a history page with information about webhooks.](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/WebhooksOverviewEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=96656828002f75a3473a0d16c718ef2d) *** ## Setting up a webhook When you create a webhook in Palm Console, you specify: * **URL** — The HTTPS endpoint that will receive events. HTTP is not supported. * **Events** — The event types you want to subscribe to. Palm generates a signing secret (format: `whsec_...`) at creation time. This secret is returned once — store it securely. You'll need it to verify that incoming requests are from Palm. ## Event format All events follow a consistent naming pattern: ``` {resource}.{action} {resource}.{sub_resource}.{action} ``` Every event payload contains: | Field | Description | | - | - | | `id` | Unique event identifier. Use for idempotency. | | `object` | Always `event`. | | `type` | The event type (e.g., `user.verification.completed`). | | `mode` | `test` or `live` — the mode of the action that produced the event. An event is delivered only to endpoints of the same mode. | | `created_at` | ISO 8601 timestamp. | | `data` | Event-specific payload. Structure depends on event type. | ## Event catalog > [!NOTE] > > **A note on naming:** Webhook event types use `user` (e.g., `user.verification.completed`); elsewhere the docs may refer to a "person." These are the same entity — the event names reflect the API resource name. ### Verification events Fired when verification processing completes. Payloads include the verification ID, risk level, match results, and — for business verification — associate results. | Event | Description | | - | - | | `user.verification.completed` | User verification finished. | | `business.verification.completed` | Business verification finished. Includes associate-level results. | ### Monitoring events Fired when Palm detects a change in a monitored business's authoritative record. These events only fire for businesses enrolled in [Monitor](/monitor/overview). | Event | Description | | - | - | | `business.registration.updated` | Registration data changed (status, name, address, officers, filings). Includes structured diffs with previous and current values. | | `business.filing.due` | A compliance filing deadline is approaching. | | `business.filing.overdue` | A compliance filing deadline has passed. | ### Filing events Fired when a [Comply](/comply/overview) filing changes status. These events cover formations, EIN applications, and other filing types. | Event | Description | | - | - | | `filing.queued` | Filing received and validated. Preparing for submission. | | `filing.ready_to_file` | Filing is ready to be processed. | | `filing.processing` | Filing is being prepared for submission to the authority. | | `filing.filed` | Filing has been submitted and is being processed. | | `filing.completed` | Filing is done as the authority accepted the filing. Result available (registration number, EIN, documents). | | `filing.canceled` | Filing was canceled. Includes `status_reason`. | **Routing by filing type.** Every filing event payload includes `data.object.type`: | `data.object.type` | Filing | | - | - | | `formation` | LLC or corporation formation | | `ein` | EIN application | > [!NOTE] > > Registered agent is **not** a filing. It is a standalone resource with its own status lifecycle and its own `registered_agent.*` events — see [Registered agent events](#registered-agent-events). On a formation it appears in the `related_items` bundle as a `registered_agent` item, never as a filing. ### Case events Fired when Palm opens or updates a case requesting information to complete a filing. See [Cases](/comply/cases). | Event | Description | | - | - | | `case.opened` | Palm opened a case and needs your response. | | `case.updated` | An open case changed. Your response was received and it moved to `under_review`, or Palm attached a document to it. | | `case.resolved` | The case closed (`resolved` or `superseded`). | ### Platform events Fired when entities are created or removed through the API. | Event | Description | | - | - | | `user.created` | A person was created. | | `user.removed` | A person was removed. | | `business.created` | A business was created. | | `business.removed` | A business was removed. | ### Document events Fired when Palm attaches a document to one of your resources on its own initiative — a filing artifact or forwarded registered-agent mail. Does not fire for documents you upload yourself. | Event | Description | | - | - | | `document.created` | Palm attached a new document to one of your businesses. `data.object` is the document; `resource_type` and `resource_id` name the business it belongs to, and `type` says what it is. | #### Document types **Forwarded registered-agent mail** | Type | Description | | - | - | | `service_of_process` | Legal service — a summons, complaint, or subpoena. | | `notice` | A notice from a government authority, such as a state compliance reminder or an annual-report deadline. | | `mail` | Forwarded correspondence with no more specific classification. | **Registered agent** | Type | Description | | - | - | | `ra_change_confirmation` | State confirmation that the registered agent on file was changed. | | `ra_resignation` | Registered agent resignation filed with the state. | | `receipt` | Payment receipt for fees paid to a state or filing portal. | **Filing artifacts** | Type | Description | | - | - | | `certificate_of_formation` | Certificate of formation issued by the state. | | `articles_of_incorporation` | Articles of incorporation or organization. | | `ein_letter` | IRS EIN assignment letter. | | `filing_confirmation` | Cover page or letter confirming a filing was received, approved, or recorded. | | `welcome_letter` | Orientation packet a state sends a newly registered business. | | `operating_agreement` | LLC operating agreement or partnership agreement. | | `bylaws` | Corporate bylaws. | ### Registered agent events Registered agent is a standalone resource, not a filing. It carries the registered-agent record on `data.object` and moves through its own status lifecycle (`pending` → `active` → `termination_requested` → `terminated`, plus `failed`). It never emits `filing.*` events. | Event | Description | | - | - | | `registered_agent.activated` | Palm became the registered agent for a business (formation provisioning completed, or a change into Palm). Status is `active`. | | `registered_agent.failed` | Provisioning (or a required state submission) failed on the assignment path; status moved to `failed`. `data.object.rejection_reason` explains why. | | `registered_agent.changed` | The registered agent moved to another provider; status is `terminated`, `provider` is `external`. | | `registered_agent.change_failed` | A partner-requested change could not be completed; status reverts to what it was before the request, so the agent of record is unchanged. `data.object.rejection_reason` explains why. | | `registered_agent.termination_requested` | You requested that Palm stop serving as the registered agent; status moved to `termination_requested`. Palm keeps forwarding mail until it completes. | | `registered_agent.terminated` | Palm is no longer the registered agent on file; status moved to `terminated`. | | `registered_agent.termination_failed` | A termination could not be completed; status reverts to `active`. `data.object.rejection_reason` explains why. | ## Example payloads Every event type has a complete, realistic example payload — including each variant (formation vs. EIN filings, each registered-agent state, `case.resolved`, `*.removed`, `business.filing.overdue`) — in the dedicated [Webhook example payloads](/developer-guide/webhook-example-payloads) reference. ## Verifying signatures All webhook payloads are signed using HMAC-SHA256. Always verify signatures before processing events. Palm sends three headers with every delivery: | Header | Description | | - | - | | `Palm-Signature` | Format: `t={timestamp},v1={signature}`. | | `Palm-Webhook-Id` | The webhook endpoint receiving the event. | | `Palm-Event-Type` | The event type being delivered. | To verify: 1. Extract the timestamp (`t`) and signature (`v1`) from the `Palm-Signature` header. 2. Check the timestamp is within 5 minutes of current time. Reject stale timestamps to prevent replay attacks. 3. Construct the signed payload: `{timestamp}.{raw_request_body}`. 4. Compute HMAC-SHA256 using your webhook secret (`whsec_...`). 5. Compare your computed signature with the `v1` value using constant-time comparison. > [!WARNING] > > Do not skip signature verification, even in development. Unsigned requests could come from anywhere. ## Retries and delivery **Timeout** — Your endpoint must respond within 10 seconds. Return a 2xx immediately, then process the event asynchronously. **Retry schedule** — If your endpoint returns a non-2xx status or times out, Palm retries: | Attempt | Delay | | - | - | | 1st retry | 1 minute | | 2nd retry | 5 minutes | | 3rd retry | 30 minutes | | 4th retry | 2 hours | After 5 total attempts (1 original + 4 retries), Palm marks the delivery as `failed`. **Auto-disable** — If a webhook accumulates 10 consecutive failed deliveries across any events, Palm automatically disables it. Check webhook execution logs in Palm Console to monitor delivery health. ## Idempotency Palm may deliver events more than once. Use the event `id` field to deduplicate. If your processing is not naturally idempotent, store processed event IDs and skip duplicates. ## Best practices * **Respond fast, process later.** Return a 2xx immediately and handle the event asynchronously. Heavy processing that exceeds the 10-second timeout will trigger retries and eventually disable your webhook. * **Always verify signatures.** Validate the `Palm-Signature` header on every request. This is your only guarantee the event came from Palm. * **Deduplicate with event IDs.** Network issues can cause duplicate deliveries. Store the `id` from each processed event to avoid processing it twice. * **Subscribe selectively.** Only subscribe to events you act on. If you don't need `user.created` events, don't subscribe — it reduces noise and load on your endpoint. * **Monitor delivery health.** Check webhook execution logs in Palm Console regularly. A pattern of failures usually means your endpoint is slow or returning errors. ## Next steps Comply overview Filings, registered agent services, and reinstatement. [Open](/comply/overview) Monitor overview Track changes to verified businesses in real time. [Open](/monitor/overview) Verify a business Confirm a business entity exists and is in good standing. [Open](/verify/verify-a-business) Verify a person Identity checks, synthetic identity detection, and watchlist screening. [Open](/verify/verify-a-person) API Reference Endpoint reference for all Palm APIs. [Open](/api-reference/introduction) # Authentication Source: https://docs.getpalm.com/get-started/authentication How to authenticate requests to the Palm API. All API requests are authenticated using API keys created in Palm Console ([platform.getpalm.com](https://platform.getpalm.com)). *** ## API keys API keys are long-lived credentials used for all server-side API calls. They're created and managed in Console. ### Key format The key prefix tells you the environment: | Prefix | Environment | Billing | | - | - | - | | `sk_test_` | Test | Not billed | | `sk_live_` | Production | Billed | ### Usage Include the API key in the `Authorization` header as a Bearer token: ```bash wrap Bash theme={null} curl -X POST https://api.getpalm.com/v1/business/registry/search \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer sk_test_...' \ -d '{ "name": "Acme Corporation", "registration_jurisdiction": "US-CA" }' ``` ### Key security When you create an API key, the raw key is returned once. Palm stores a cryptographic hash — not the key itself. If you lose a key, you'll need to create a new one. Each API key is tied to one organization. All requests authenticated with that key operate within that organization's context. ### Test vs production The key prefix determines the **mode**. Test keys run in an isolated sandbox — never billed, never touching real filings or providers — and return production-shaped responses and webhooks so you can build a full integration before going live. See [Test mode](/get-started/test-mode) for how it works, deterministic verification results, and simulating filing outcomes. ## Error handling | Status code | Meaning | | - | - | | `400 Bad Request` | Invalid request parameters. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Valid credentials but insufficient permissions. | | `404 Not Found` | Resource not found. | | `429 Too Many Requests` | Rate limit exceeded. | | `500 Internal Server Error` | Server error. | Common causes of `401` errors: missing `Authorization` header, malformed Bearer token, or expired / revoked API key. Error responses follow the [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807) format: ```json wrap JSON theme={null} { "type": "https://api.getpalm.com/problems/validation_error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/business/registry/search" } ``` ## Best practices * **Store API keys securely:** Use environment variables or a secrets manager. Never commit keys to source control. * **Use test keys for development:** Reserve `sk_live_` keys for production systems. * **Rotate keys periodically:** Create new keys and deprecate old ones on a regular schedule. * **Monitor key usage:** Check Console for unusual activity patterns. ## Rate limiting All authenticated requests are subject to rate limits. When you exceed the limit, the API returns `429 Too Many Requests` with the following headers: | Header | Description | | - | - | | `X-RateLimit-Limit` | Maximum requests per minute. | | `X-RateLimit-Remaining` | Requests remaining in the current window. | | `X-RateLimit-Reset` | Unix timestamp when the window resets. | Back off and retry after the reset window. ## Next steps Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) Search the registry Search all US registered businesses in the network by name, jurisdiction, or location. [Open](/onboard/registry-search) # Get access Source: https://docs.getpalm.com/get-started/get-access Create a Palm account, generate API keys, and start building with Palm. *** ## Get started **1. Create your Palm account** Sign up at [platform.getpalm.com/signup](https://platform.getpalm.com/signup). Account creation is self-serve, so you reach Palm Console straight away. **2. Create your API keys** In Console, go to **API Keys** and generate a key. Create test and production keys separately. You can rotate or revoke either at any time. **3. Build against test mode** Start on a test key. [Test mode](/get-started/test-mode) is a full sandbox: the same endpoints, response shapes, and webhooks as production, with no cost and no real filings. **4. Talk to our team** Palm enables Comply products: formations, EIN applications, and Registered Agent services. [Book a call](https://cal.com/team/getpalm/palm-apis) when you are ready for production or need access to Comply. ## API keys Palm issues two types of API keys, distinguished by prefix: | Key type | Prefix | Base URL | Description | | - | - | - | - | | Test | `sk_test_` | | Non-billable. Use to build and validate your integration. | | Production | `sk_live_` | `https://api.getpalm.com` | Live business data. Metered usage. | ## Next steps Palm Console Manage API keys, webhooks, activity logs, and billing. [Open](/get-started/palm-console) Authentication How to authenticate requests to the Palm API. [Open](/get-started/authentication) Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) # How Palm works Source: https://docs.getpalm.com/get-started/how-palm-works How Palm thinks about business identity. *** ## Acceptance and Accuracy The market for business identity has two sides, and most of it is focused on the wrong one. | **Acceptance** | **Accuracy** | | - | - | | **Acceptance is the question platforms ask when a business shows up:** Can I trust this entity enough to do business with them? This is KYB — identity verification at the point of onboarding. It's a one-time check. Most providers answer it by querying public databases and returning a confidence score. | **Accuracy is the harder question:** Is this business actually who they say they are, and are they still in good standing? This requires tracing the legal connections between businesses, people, and government authorities — not just at onboarding, but continuously. | Palm does both. But we're built on Accuracy first. When Palm verifies a business, it doesn't rely on aggregated public records that anyone can access. It traces identities back to the authoritative sources that create them: state registries and the IRS. This is the difference between knowing a business appears in a database and knowing it is what it claims to be. ## The network Palm powers a network of 125M businesses. Each identity in the network is connected to the authoritative government sources that created it. When your platform verifies a business through Palm, that verification doesn't disappear after the API call. The verified data enters a centralized store of every data point Palm has confirmed against authoritative sources. That data then becomes reusable across the network. A business verified by one partner doesn't need to start from zero with the next. This is what makes Palm a network, not just an API. Every verification strengthens the graph. Every monitored business adds a signal. The more platforms that use Palm, the more accurate and current the network becomes. ![Representation of how the Palm network works.](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/HowItWorksChart.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=0af33936776cbe38ddde6c937c2dda02) ## Concepts Palm's data model has two core entities. Understanding them is essential before working with any endpoint. ### Everything starts with a Search Before you verify a business, enroll it in monitoring, or trigger a compliance action, you find it. Search is not a prerequisite — it is the entry point to every workflow Palm supports. Think of Palm's registry as a live index of 125 million US businesses, sourced directly from all 50 Secretary of State offices and the IRS. When a business registers with a state, it enters the registry. When it files an annual report, changes its Registered Agent, or updates its officers, that change propagates. You are always working with authoritative data, not an aggregated snapshot. This matters because the first question any onboarding flow has to answer is: does this business actually exist? Registry search answers that question before you spend a single verification credit. ### Business A Business is a registered business entity — an LLC, corporation, or any other legal structure recognized by a government authority. It has: * **Vault data:** Legal name, EIN, entity type, registration jurisdiction, and any other business details you collect * **Metadata:** External IDs and custom fields you define to link the business back to your system * **Display name:** A human-readable label for the entity ### User A User is a person — associated or not to a business. Users represent the humans behind business entities: owners, beneficial owners, officers, Registered Agents, or authorized signers. It has: * **Identity data:** Name, date of birth, email, and other PII stored in the vault * **Metadata:** External IDs and custom fields you define to link the user back to your system ## Palm ID Every real business in the United States has a Palm ID. It's a permanent identifier for the entity itself. When you submit a business for verification, Palm resolves the input to the correct Palm ID. Verification is the act of matching your data to an existing identity. This is what makes identity reusable across the Palm network. The verified data linked to a Palm ID persists regardless of which partner triggered the verification. A business verified by one partner doesn't need to start from zero with the next. ## The vault The vault is where partner-collected data lives before verification. When a business onboards through your platform, the data they submit — name, EIN, address, officers — is stored in your vault. This data is unverified by default. Each partner maintains their own vault. The vault supports stepwise onboarding, so you can collect data incrementally rather than requiring everything upfront. Sensitive fields are stored with field-level encryption. ![Representation of how the Palm vault works](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/HowItWorks2.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=a859bf202738ab29725986061f2d80e3) ## Next steps Get access Request API keys and start building with Palm. [Open](/get-started/get-access) Onboard overview Find and onboard businesses into your platform. [Open](/onboard/overview) Verify overview Verify businesses and people. KYB, KYC, risk assessment, and ongoing re-verification. [Open](/verify/overview) # MCP server Source: https://docs.getpalm.com/get-started/mcp-server Connect an AI assistant to Palm over the Model Context Protocol. Palm hosts a remote [Model Context Protocol](https://modelcontextprotocol.io/) server so AI assistants can work with your Palm account directly — onboard and verify businesses, search the registration registry, manage monitoring, and file with the state. *** > [!NOTE] > > The MCP server is in early access. To share feedback, ask your assistant to send it to Palm. ## Connect The server is hosted at `https://mcp.getpalm.com/mcp` and uses OAuth, so there is no API key to paste. Your assistant opens a browser, you sign in with your Palm Console account, and the connection is authorized. > [tab] Claude Code > > ```bash theme={null} > claude mcp add --transport http palm https://mcp.getpalm.com/mcp > ``` > > Run `/mcp` in Claude Code to complete the sign-in. > [tab] Codex > > ```bash theme={null} > codex mcp add palm --url https://mcp.getpalm.com/mcp > codex mcp login palm > ``` > [tab] Cowork and Claude Desktop > > Add Palm as a custom connector: > > 1. Go to **Customize > Connectors** and click **+**. > 2. Choose **Add custom connector**. > 3. Enter `https://mcp.getpalm.com/mcp` as the server URL and click **Add**. > 4. Click **Connect** and sign in with your Palm Console account. > > On a Team or Enterprise plan, an owner adds the connector once under **Organization settings > Connectors**, and each member then connects and signs in with their own Palm account. > [tab] Other clients > > ```json theme={null} > { > "mcpServers": { > "palm": { > "type": "http", > "url": "https://mcp.getpalm.com/mcp" > } > } > } > ``` Any MCP client that supports remote servers over HTTP can connect. Point it at the same URL and complete the sign-in prompt — the server registers the client for you, so there are no OAuth credentials to configure by hand. ## Access and scoping Every call is made with your own credentials, so the server sees exactly what your Palm Console account sees — the same organization, the same records, the same permissions. Connecting an assistant grants it no access beyond your own. ## What the assistant can do | Area | Capability | | - | - | | Onboard | Search the business registration registry, pull a registry record, check name eligibility | | Verify | Add a business to your account, submit it for verification, read the result | | Monitor | Turn monitoring on or off for a business and choose which events it subscribes to | | Comply | Form an LLC or corporation, apply for an EIN, change a registered agent, work open cases, retrieve filed documents | The server also ships guided workflows for the longer jobs — a full KYB review, a portfolio compliance sweep, an end-to-end formation — so an assistant follows Palm's procedure instead of improvising one. ## Next steps Get access Request access and provision your Palm Console account. [Open](/get-started/get-access) Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) # Meet Palm Source: https://docs.getpalm.com/get-started/meet-palm The business identity network built on accuracy. Palm is the only business identity built for business. We verify businesses & entities, monitor their compliance, and keep their identity accurate & current across every jurisdiction. Helping you onboard great customers and keep them in good standing. *** ## The problem Every business in the US exists as a fragmented set of records scattered across state registries, federal agencies, and third-party databases. There is no unified, portable identity that ties a business to its people, reflects what is actually known about it across every source, and travels with it across platforms. This creates real cost. Business owners re-prove who they are every time they open a bank account, apply for a loan, or engage a new vendor. Platforms spend too much acquiring, verifying, and monitoring business customers — reverifying and re-requesting information that already exists somewhere else. And the data used to verify businesses is often stale, pulled from aggregators updated quarterly while registries change daily. The deeper issue: compliance and verification live in entirely separate systems. Every annual report, every Registered Agent interaction, every state filing is an identity event — it confirms who owns the business, where it operates, and whether it's in good standing. But none of that signal flows back to the platforms that verified the business in the first place. ## What Palm does Palm connects directly to all 50 state registries and the IRS to verify businesses and their people in real time, monitor them continuously through event-driven alerts, and use compliance as the recurring mechanism that keeps identities current — all through a single API. **Verify once:** Palm verifies business entities and the people behind them against authoritative government records: Secretary of State registries and the IRS. When Palm verifies a business, that identity enters the network and can be carried forward rather than rebuilt from scratch. **Monitor continuously:** Palm tracks the business and fires webhooks when something actually changes: a registration lapses, an officer changes, a filing falls overdue. Monitoring is event-driven: your platform re-verifies only when there's a reason to, not on a schedule. **Keep identity accurate through compliance:** When Palm files an annual report, registers an agent, or submits a formation, the state's response updates the business's record in Palm. This is what separates accuracy from acceptance — compliance activity keeps identity data confirmed at the source, not just checked once at onboarding. ## The network Palm maintains a network of 125M businesses. Every identity in the network is sourced from the authorities that create them and kept current by the compliance activity that sustains them. **How data flows in:** Palm connects directly to all 50 Secretary of State registries and the IRS in real time. Palm also writes to these sources — every formation, annual report, and compliance filing Palm processes flows back into the registry records. This two-way connection means identity data stays current at the source, not just inside Palm. **Identity is portable:** A business verified through Palm carries that identity forward. It doesn't need to be re-verified from scratch by the next platform. The business owns its identity, and as a partner you have access to all permissioned information. **The network grows with use:** Every verification adds a business to the network. Every compliance filing refreshes an identity already on it. More businesses mean more compliance activity. More compliance activity means fresher data. The network gains both breadth and freshness over time. ## What you can do today Onboard Find businesses in Palm's registry, pull registration data, and get them into your platform. [Open](/onboard/overview) Verify Run identity, risk, and compliance checks on businesses and people that go beyond the public record. [Open](/verify/overview) ![Radar icon](https://mintcdn.com/palmfinance/daYZx5iu2nApVxpw/images/custom-radar-moss.svg?fit=max\&auto=format\&n=daYZx5iu2nApVxpw\&q=85\&s=f8fa80b7171e475122398f9b93e98fdd) Monitor Track changes to registration status, filings, and officers. Get webhooks when something changes. [Open](/monitor/overview) Comply Formations, EIN applications, annual reports, and Registered Agent services. Palm handles the filings so businesses stay in good standing. [Open](/comply/overview) ## Next steps How Palm works Learn how Palm thinks about business identity [Open](/get-started/how-palm-works) Get access Request API keys and start building with Palm. [Open](/get-started/get-access) # Palm Console Source: https://docs.getpalm.com/get-started/palm-console Palm Console is where you manage your integration. Palm Console is where you manage your integration. This page covers what you'll use most as a developer. *** ## API keys Generate and rotate API keys for sandbox and production environments. Every API request requires a key. See [Authentication](/get-started/authentication) for how to include it. ## Webhook configuration Register endpoint URLs, view delivery logs, and manage signing secrets. See [Webhooks](/developer-guide/webhooks) for payload formats and event types. ## Workflows Configure which checks run during verification — identity verification, TIN verification, risk assessment, and more. See [Verification Reference](/verify/verification-reference) for the full list of check types. ## Activity and logs View API request history, webhook delivery attempts, and event timelines. Use this to debug failed requests, inspect payloads, and trace a verification or monitoring event end to end. ## Businesses and users Browse all business and user records created through the API. Each record links to its verification status, monitoring events, and registration data. ## Billing View usage, manage your plan, and access invoices. Console is available at [platform.getpalm.com](https://platform.getpalm.com). # Test mode Source: https://docs.getpalm.com/get-started/test-mode Build and validate your entire integration in an isolated sandbox — no cost, no real filings, and the same responses and webhooks you get in production. Test mode is a full sandbox. Anything you create with a test API key — businesses, verifications, filings, documents, and webhooks — lives in an isolated test environment that mirrors production behavior, never incurs cost, and never creates real filings or operations. You can build and verify an entire integration end to end on a test key before you ever go live. *** ## How mode is set Every request runs in exactly one mode, determined by the API key you authenticate with: | Prefix | Mode | Billing | | - | - | - | | `sk_test_` | Test (sandbox) | Never billed | | `sk_live_` | Live (production) | Billed | Create both key types in [Palm Console](https://platform.getpalm.com), and use the Console **test/live toggle** to view the matching data. There is nothing to configure beyond the key — swap the key and the same endpoints operate against the other mode. ## What test mode guarantees * **Isolation.** Test data and live data are separate. Test records never appear in live API results or the live Console view, and live records never appear in test. * **No cost.** Test requests are never metered or billed. * **No real filings or operations.** Test-key filings are simulated: nothing is submitted to any state, no EIN application is actually filed, and no real operations work or monitoring is created. * **Production-shaped responses.** Test responses use the same schema, the same IDs, and the same webhook payloads as live, so what you build against test works unchanged in live. ## Onboard [Registry search](/onboard/registry-search) is available in test mode, so you can build and validate your search-driven onboarding flow before going live. ## Verify Verifications in test mode use the same request and response shapes as live. ### Person verification Person (KYC) verifications in test mode are deterministic, so you can build against a known outcome. Use a **reserved test SSN** to force a specific risk level; any other SSN returns a clean low-risk pass. | Test SSN | Risk level | Notes | | - | - | - | | `111-11-1100` | `low` | Clean pass, all fields match. | | `111-11-1300` | `medium` | | | `111-11-1500` | `high` | | | `111-11-1700` | `critical` | Synthetic-identity indicators; SSN does not match. | | Any other SSN | `low` | Default clean pass. | The verification payload (risk, match results, synthetic, watchlist) is populated to match the outcome, so a `critical` result carries realistic `reasons` and match failures you can render and route on. ### Business verification Business verification is available in test mode, so you can build and validate your business onboarding flow before going live. Each associate (beneficial owner) is verified as a person, so you can steer an associate's result with the reserved test SSNs above. ### Selecting an outcome directly For both business and person verification you can also set the reserved `_simulate` key in the request `metadata` to force a specific result — a risk level (`low`, `medium`, `high`, `critical`), a named scenario (such as `no_match`), or `fail` for a system error. It takes precedence over the reserved test SSNs and is ignored in live mode. See the request reference for each endpoint's full list of values. > [!NOTE] > > Without `_simulate`, business verification in test mode always returns a deterministic clean pass — it never queries live registry or IRS data. ## Monitor: enrollment only Enrolling a test business in [Monitor](/monitor/overview) works like it does in live — the monitoring subscription is created, so you can build and verify the enrollment flow. It is only a simulation, though: Palm does not watch any authoritative record for a test business, so no real monitoring is taking place and monitoring events (`business.registration.updated`, `business.filing.due`, `business.filing.overdue`) do not fire from real-world changes. ## Comply: filings auto-advance In live mode, a filing progresses as Palm's operations team and the state process it. In test mode there is no one in the loop — a filing you create on a test key **advances through its lifecycle automatically**, firing the same `filing.*` webhooks at each transition, so you can watch `queued → ready_to_file → processing → filed → completed` play out in a few seconds and exercise your webhook handling. Bundled filings behave like production: an EIN created under a formation stays `queued` until its parent formation reaches `completed`, then advances on its own. Registered-agent provisioning on a test formation activates automatically and fires `registered_agent.activated`. ### Simulating outcomes By default a test filing runs the happy path to `completed`. Set the reserved `_simulate` key in the filing's `metadata` on the create request to drive a specific outcome. The value is `[:case_][:][:auto]`. **Terminal outcome** | `metadata._simulate` | Result | | - | - | | `completed` | Default. Filing runs through to `completed`. | | `canceled` | Filing ends `canceled` — fires `filing.canceled`. | **Simulating a case** Append `:case_` to open a [case](/comply/cases) when the filing reaches that status — mirroring Palm needing something from you before the filing can continue. `` is any non-terminal filing status you receive: `case_queued`, `case_ready_to_file`, `case_processing`, or `case_filed`. The filing holds at that status and fires `case.opened`, then resumes to its terminal once you resolve the case by responding at `POST /v1/case/{case_id}/response`. Append `:auto` to have the case resolve itself after a short delay instead of waiting for your response. Add a scenario segment to choose which case opens. Every case you can receive in production has one, so you can build and check each handler on a test key. A filing with no `:case_` opens no case. | Scenario | Case `kind` | What it asks for | What your response does | | - | - | - | - | | *(none)* | `missing_information` | A corrected address, under the field name your filing request uses: `principal_address` on a formation or foreign qualification, `mailing_address` on an EIN application. | Resolves the case; the filing continues. | | `legal_name_change` | `legal_name_change` | `legal_name` — another business name to file under. | Renames the filing, any bundled filing not yet submitted, and the business before `case.resolved` fires. | | `document` | `missing_information` | One `document` field, with a sample letter from Palm in `request.documents`. | Relates the document you return to the case and the filing. | | `metadata._simulate` | Result | | - | - | | `completed:case_processing` | Opens an information request at `processing`; resumes to `completed` after you respond. | | `completed:case_processing:legal_name_change` | Opens a name-change case at `processing`; your `legal_name` answer renames the filing, which then completes under the new name. | | `completed:case_processing:document` | Opens a case that carries a document and asks for one back; resumes to `completed` after you respond. | | `canceled:case_filed:auto` | Opens a case at `filed`, auto-resolves, then ends `canceled`. | ```json wrap JSON theme={null} { "name": "Acme Holdings LLC", "jurisdiction": "US-NC", "metadata": { "_simulate": "completed:case_processing:legal_name_change" } } ``` A few details match production and are worth building against: * **Information request.** Answer with the same address object the filing request takes. * **Name change.** A filing already at `filed` keeps the name it was submitted under, so open this case at `case_queued`, `case_ready_to_file`, or `case_processing` to see the rename. With `:auto` the case closes without a response and nothing is renamed. * **Document.** Download the sample letter through the [document endpoints](/api-reference/v1/documents/retrieve-document-metadata), [upload a file](/api-reference/v1/business/upload-document) of type `other` to the business, and answer the `document` field with the id of the upload. > [!NOTE] > > `_simulate` is a test-only control; it is ignored in live mode. On a bundled formation + EIN it applies to the formation — to drive an EIN to its own outcome, submit a standalone EIN filing with its own `_simulate`. ## Webhooks in test mode Webhook endpoints are registered per mode: an endpoint you create with a test key (or while the Console is in test) is a **test endpoint**; one created in live is a **live endpoint**. Events are delivered only to endpoints of the same mode, so test traffic reaches your test endpoint and never your production one. Point them at different URLs to keep sandbox and production deliveries apart. Every event also carries a top-level `mode` field (`test` for sandbox events) so your handler can assert it. See [Webhooks](/developer-guide/webhooks) for setup, signature verification, and retries. ## Going live When your integration works end to end in test, moving to production is a key swap: 1. Replace your `sk_test_` key with an `sk_live_` key from Console. 2. Register your **live** webhook endpoints (test endpoints do not receive live events). 3. Expect real timelines and costs — live filings are processed by Palm operations and the state, not the simulator, so they progress on real-world schedules and are billed. ## Next steps Authentication API keys, the Authorization header, and key security. [Open](/get-started/authentication) Webhooks Register endpoints, verify signatures, and handle retries. [Open](/developer-guide/webhooks) Form a business Create a formation and watch it progress in test. [Open](/comply/form-a-business) Verify a person Run KYC with deterministic test outcomes. [Open](/verify/verify-a-person) # Palm Documentation Source: https://docs.getpalm.com/introduction Learn how to get started with the Palm Platform # Palm Documentation Palm is the business identity network. Verify businesses and the people behind them against authoritative records, monitor them for change, and file on their behalf — through one API. IRS FinCEN SOS Lawsuits Tax Permit License Insurance Your Company Inc. ID: 4820 - 3921 - 9741 ![Decorative globe](/images/globe.svg) ## Get started Onboard Verify ![Radar icon](https://mintcdn.com/palmfinance/daYZx5iu2nApVxpw/images/custom-radar-moss.svg?fit=max\&auto=format\&n=daYZx5iu2nApVxpw\&q=85\&s=f8fa80b7171e475122398f9b93e98fdd) Monitor Comply [See all use cases ](/use-cases/overview) ## Resources Contact us Talk to us about questions, issues or any other requests you might have (technical, billing, integration issues, access, etc.) [Open](mailto:support@getpalm.com) API status Monitor API uptime and check for any service incidents. [Open](https://status.getpalm.com) Console Manage your API keys, view usage, and test in the Palm Console. [Open](https://platform.getpalm.com) # Monitor a business Source: https://docs.getpalm.com/monitor/overview Track changes to businesses in real time. A verification tells you a business is real and in good standing right now. Monitor tells you when that changes. Palm watches authoritative sources for registration changes, officer updates, address moves, and compliance deadlines, and sends you a webhook when something happens. ![Image a business's information, and warnings about their status](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/MonitorOverviewEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=5999a8d0f97033f02fde3e8cbfcd0849) *** ## Why monitoring The industry default is scheduled re-verification — running the same check on every business in your portfolio annually or quarterly, regardless of whether anything changed. This is expensive and leaves blind spots. A business verified in January could dissolve in March, and you wouldn't know until the next scheduled check. Monitor eliminates those blind spots. Instead of re-verifying on a schedule, you get notified when something actually changes — and only re-verify when the change warrants it. Palm watches authoritative sources continuously and pushes events to your webhook endpoint when it detects a change. No change, no noise. When Monitor does detect a problem, you can act on it through Comply — file the overdue report, resolve the compliance gap — without leaving the API. Detection and resolution in one integration. ## What Monitor tracks When you enroll a business in monitoring, Palm watches for changes across its registration data: * **Registration status:** Active, suspended, dissolved, revoked. If a business falls out of good standing or gets administratively dissolved, you'll know immediately. * **Legal name:** Name changes at the state level, including DBA updates. * **Principal address:** When the address on file with the state changes. * **Officers and directors:** Changes to the people listed on the state filing. * **Registered Agent:** When the business changes its Registered Agent. * **New filings:** Annual reports, amendments, and other documents filed with the state. * **Compliance deadlines:** Upcoming filing due dates and overdue notices. ## How it works **1. Start monitoring** Identify the business you want to watch by Palm ID, by registration jurisdiction and number, or by a business already in your portfolio. Palm begins watching its registration data. **2. Receive events** When Palm detects a change, it sends a webhook event to your endpoint. Events include structured change data with the new values. **3. Act** Use the event to update your records, alert your compliance team, file a compliance action through Comply, or — for structural changes like officer updates — re-verify to run Person Verification on new individuals. ## Event types Monitor produces three event types, all delivered through [webhooks](/developer-guide/webhooks): * **`business.registration.updated`:** Any registration data changed. This is the core monitoring event. The payload includes a `changes` array where each entry describes what changed, the previous value, the current value, and a human-readable summary. A single event can contain multiple changes (e.g., a name change and an address change filed together). * **`business.filing.due`:** A compliance filing deadline is approaching. Includes the filing type, frequency, and due date. Use this to proactively remind your users or trigger compliance workflows before deadlines pass. * **`business.filing.overdue`:** A compliance filing deadline has passed without a filing on record. A missed annual report can lead to suspension or administrative dissolution — this event lets you catch it early. ## Event payloads Registration change events carry a `changes` array with one entry per attribute that changed, each giving the previous value, the current value, and a human-readable summary. A single event can carry several changes when they were filed together: a name change and an address change submitted at the same time arrive as one event. Filing deadline events carry the filing type, frequency, and due date. In both, `data.business` identifies which business changed. It is not the full record, so retrieve the business when you need more. For the payload of every monitoring event, see [Webhook example payloads](/developer-guide/webhook-example-payloads). ## When to use monitoring * **Ongoing compliance obligations:** If you carry businesses on your platform and need to know when their compliance state changes, monitoring is cheaper and more reliable than any scheduled manual ops. * **Lending and underwriting:** A business that dissolves or loses good standing after you've extended credit is a material risk. Monitoring catches these changes as they happen. * **Insurance:** Policy binding depends on the business being active and in good standing. Monitor lets you catch status changes between renewal cycles. * **Marketplace and platform trust:** If your platform lists or transacts with businesses, monitoring ensures you're not carrying dissolved or suspended entities. ## Prerequisites * A Palm API key — [Get access](/get-started/get-access) * A webhook endpoint configured to receive events — [Webhooks](/developer-guide/webhooks) A verification is not required. Palm recommends verifying a business before you take it on, but monitoring does not depend on it. ## Start monitoring There are two ways to switch monitoring on. Which one you use depends on whether you already hold the business in your portfolio. **Monitor a business** (`POST /v1/business/subscription`) identifies the registration directly, with no portfolio business required. Palm resolves the identifier, creates the portfolio business, and returns it with the subscription. See [Monitor business](/api-reference/v1/monitor/monitor-business). **Monitor a portfolio business** (`POST /v1/business/{business_id}/subscription`) takes a business you already hold, for example one you have verified. The body carries the event types and nothing else. See [Monitor portfolio business](/api-reference/v1/monitor/monitor-portfolio-business). ### Identify the business Send exactly one identifier: either `palm_id`, as returned by [registry search](/onboard/registry-search), or `registration_jurisdiction` and `registration_number` together. Any other combination returns `400`, and nothing is created. ### Monitoring is per registration Each identifier names a registration, not a company. A business registered in several states has a separate registry record in each one, each with its own Palm ID. A Delaware company qualified into Michigan and Connecticut has three. Subscribe once for each registration you want to watch. The subscriptions are independent. Every record carries both the jurisdiction it is registered in and the jurisdiction it was formed in, and the two differ when a business has expanded beyond its home state. ### When the identifier does not resolve An identifier that does not match exactly one registration is rejected, and no subscription is created. * **`404`** No registration matches the identifier. The response names what was searched. Check the registration number and jurisdiction, then retry. * **`422`** More than one registration matches. A registration number can appear against more than one record. The response lists the `candidates`, each with its `palm_id`, name, registration jurisdiction, and formation jurisdiction. Resubmit with the `palm_id` you want. A registration that is not linked to a registry source also returns `422`. Contact Palm if you receive this; changing the request will not resolve it. ### The portfolio business Palm creates When you monitor by identifier, Palm creates the portfolio business, links it to the resolved registry record, and returns it. From there it behaves like any business you added yourself: you read, change, and cancel the subscription the same way, receive the same alerts, and see the business in your portfolio. * **Filled in from the registry record:** legal name, entity type, formation date, formation and registration jurisdiction, and principal address. The registration number is stored in the business metadata. * **Reused, not duplicated:** if your organization already holds a portfolio business for that registry record, Palm reuses it instead of creating a second one, so you do not receive duplicate alerts. Businesses pointing at different registrations of the same company are kept separate. Test mode behaves the same as live. See [Test mode](/get-started/test-mode). ## Managing a subscription * **Check subscription status:** `GET /v1/business/{business_id}/subscription` returns the current monitoring state, including which event types are active. * **Update event types:** `PATCH /v1/business/{business_id}/subscription` lets you change which monitoring events you receive for a specific business. For example, you might subscribe to registration changes but not filing deadlines. * **Unsubscribe:** `DELETE /v1/business/{business_id}/subscription` stops monitoring for that business. You'll stop receiving events immediately. For the full request/response schemas, see the [API Reference](/api-reference/introduction). ## How Monitor connects to Onboard, Verify, and Comply Monitor sits between verification and action. Onboard finds the business. Verify gives you a point-in-time snapshot. Monitor keeps that snapshot current. Comply lets you act on what Monitor finds. How you respond to a monitoring event depends on what changed: **Status and filing events → Act directly:** When Monitor fires `business.filing.overdue` or a registration status changes to suspended, you already know what happened. Use Comply to file the annual report, alert your compliance team, or pause the account. No re-verification needed — the monitoring event gives you the answer. **Structural changes → Re-verify, then act:** When Monitor reports an officer change, the event tells you who was added or removed — but it doesn't run Person Verification on the new individual. Re-verifying through Verify runs identity checks, watchlist screening, and risk assessment on the new officers. This is the scenario where re-verification adds a signal that monitoring alone won't provide. Detection, verification, and resolution through the same API — one integration for the full lifecycle. ![Representation of how monitoring cascades into actions across Palm.](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/MonitorOverviewFlowChart.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=7841f34a56a5eca8d0aa32c2efc84063) ## Next steps Monitor API reference Full reference for the monitoring subscription endpoints. [Open](/api-reference/v1/monitor/monitor-business) Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) Comply overview Act on behalf of businesses — formation, filings, Registered Agent services, and reinstatement through the same API you use to verify and monitor. [Open](/comply/overview) Webhooks Receive real-time notifications when events occur across Verify, Monitor, and Comply. [Open](/developer-guide/webhooks) Onboard overview Find and onboard businesses into your platform. [Open](/onboard/overview) # Check name eligibility Source: https://docs.getpalm.com/onboard/name-eligibility Check a proposed business name against the state's naming rules and registry before your member files, across all 50 states, DC, and Puerto Rico. Naming problems are the leading reason formations get rejected: a missing ending, a restricted word, a name another business holds. Each state sets its own rules for all three. An ending that files in one state fails in the next, and a counseling practice that forms as an ordinary LLC in one state needs a professional LLC in another. Palm builds each state's naming rules from its statutes and regulations, and tests them against the names the state has registered. The rules cover all 50 states, DC, and Puerto Rico, for LLCs, professional LLCs, corporations, and professional corporations. The name-eligibility endpoints put this check in your flow, at the moment a member proposes a name. The member corrects the name in your form and carries an eligible name into the formation. *** ## How it works 1. [Offer the valid endings](#offer-valid-endings-up-front). Show the endings the state accepts, or append the recommended one, before your member types a name. 2. [Check the name](#check-a-name). One call measures the name against the state's naming rules and its registry. 3. [Read the result](#read-the-result). `eligible` is the answer. Each violation explains a problem in terms your member can act on. 4. [Correct the name](#correct-the-name). Palm returns the fix for a missing or misspelled ending, and eligible alternatives on request. 5. [File](#from-check-to-formation). Carry the eligible name into [Form a business](/comply/form-a-business). ## Offer valid endings up front Most states require a business name to include a word or abbreviation that shows the entity type, such as `LLC`, `Inc.`, or `P.C.`. The accepted-endings endpoint returns the endings a state accepts for each entity type, with a recommended default. Call it before you collect a name. Omit `entity_type` to receive every entity type the state allows in one response. ```bash Bash wrap theme={null} curl https://api.getpalm.com/v1/business/registry/US-TX/name-eligibility/designator \ -H 'Authorization: Bearer sk_test_...' ``` For each entity type, the response lists the endings the state accepts, a recommended default to use when you append one, and whether an ending is required at all. California corporations, for one, need none. In Puerto Rico the list includes Spanish endings, such as `Corporación`. An entity type the state does not allow is left out: California has no professional LLC, so it returns `llc`, `corporation`, and `professional_corporation` only. The full response is in [Get accepted name designators](/api-reference/v1/registry/get-accepted-name-designators). ## Check a name ```bash Bash wrap theme={null} curl 'https://api.getpalm.com/v1/business/registry/US-TX/name-eligibility?name=Maple%20Street%20Ventures%20LLC&entity_type=llc' \ -H 'Authorization: Bearer sk_test_...' ``` The state, `name`, and `entity_type` are required. Four optional parameters extend the check: `suggest` returns eligible alternatives, `screen` adds content screening, and `profession` and `subtype` apply the rules for [professional and specialized entities](#professional-and-specialized-entities). Every parameter is described in [Check business name eligibility](/api-reference/v1/registry/check-business-name-eligibility). ## Read the result `eligible` is the answer: `true` when the name follows the state's naming rules and no registered business holds it. Each item in `violations` names the `rule` it comes from, a `severity`, and a plain-language `message` you can show your member. The full response is in [Check business name eligibility](/api-reference/v1/registry/check-business-name-eligibility). Each violation carries a `severity`: | Severity | What it means | Example | | - | - | - | | `error` | The name cannot register as submitted. Makes `compliant` and `eligible` false. | `Maple Street Ventures` has no ending, which Texas requires. | | `needs_approval` | The name can register only with sign-off from the agency the message names. Does not change `eligible`. | `Golden Bear Bank Trust` needs approval from California's Department of Financial Protection and Innovation. | | `advisory` | A concern to show your member. Does not change `eligible`. | With `screen=true`, `Federal Reserve Consulting LLC` is flagged for implying a link to a federal agency. | > [!NOTE] > > An eligible name can carry violations. Base your decision on `eligible`, and show every `needs_approval` and `advisory` message to your member. A non-empty `violations` list on its own does not mean the name failed. A rule usually carries the same severity everywhere, but a state can set it differently, so read `severity` on each violation. Every rule is listed in the [Rule reference](#rule-reference) at the end of this page. ## Correct the name Where the correction is unambiguous, the violation carries a `fix` your member can accept in one step: * A missing ending gets a fix to add the state's recommended one (`append_designator`), such as "Add the required 'LLC' designator." * A misspelled or wrong ending gets a fix naming the accepted one (`fix_designator_typo`), such as "Did you mean 'LLC'?" for `LLCC`. The fix describes the change, and your form applies it. Pass `suggest=true` and Palm also returns eligible alternative names. Palm runs each one through the same check before returning it, so every alternative follows the state's naming rules and is available in the registry. Up to five come back, and they vary between calls. ## Professional and specialized entities Many states let licensed professions practice only through a professional LLC or professional corporation, and some set the professional entity's name by the profession. Palm applies both, so a member forming a practice learns which entity type and which name the state requires before they file. * A name that signals a licensed profession. When the name of an ordinary LLC or corporation carries a title the state reserves for licensees, Palm adds a `professional_entity_required` advisory that names the professional form to use. `Beautiful Chaos Counseling LLC` in North Carolina gets one. The advisory does not block the name, and everyday words shared with unlicensed trades, such as "therapy", are not flagged. When you know your member's profession, pass `profession`, and Palm returns the advisory whatever the name says. * An entity type the state does not allow. `entity_type_unavailable` means no name is eligible for that entity type, and the message names the form the state uses instead. California organizes licensed professions as professional corporations only. * Names set by profession. California requires a pharmacy corporation's name to include "pharmacy", "pharmacist", or "pharmaceutical". Pass `profession=pharmacy`, and a name without those words fails with a message that names them. Without `profession`, Palm returns a `profession_rules_not_checked` advisory instead. The [API Reference](/api-reference/v1/registry/check-business-name-eligibility) lists every `profession` value. * Sub-forms. Pass `subtype` (`low_profit`, `close`, `benefit`, or `statutory_close`) to apply the naming rules for low-profit LLCs, close corporations, and benefit corporations. In Illinois, a low-profit LLC's name must end with `L3C`. A `subtype` changes the result only in states that name the sub-form differently. The accepted-endings endpoint lists ordinary endings only, so check sub-form names with the name-eligibility endpoint. ## How availability is compared A name is taken when a registered business that holds its name has the same name. Palm compares names without regard to case, punctuation, accents, or "&" versus "and". Many states also say the entity ending does not distinguish two names. Palm applies each state's comparison as its law is written: * Most of these states compare across every kind of business. In Illinois, `Garcia Construction LLC` is unavailable because `Garcia Construction, Inc.` is registered. * Some states, such as California and Maryland, set the ending aside only between two businesses of the same kind, so an LLC and a corporation there can share a name apart from the ending. * In states whose law does not address the ending, a different ending makes a different name. The ending comparison applies to legal names. A registered assumed name blocks only the same name as written. Palm does not compare the other differences a state may disregard, such as articles, plurals, abbreviations, and sound-alike spellings, so the state can refuse a name Palm reports as available. To see which registered businesses hold a similar name, [search the registry](/onboard/registry-search). ## From check to formation Run the name-eligibility check before you submit a formation. Formation validation does not check the name against the naming rules or the registry. Profession and sub-form rules can be checked only on this endpoint, because a formation request carries no `profession` or `subtype`. The state makes the final decision on every name. If it declines one after submission, Palm opens a `legal_name_change` [case](/comply/cases) on the filing, and the filing continues under the new name your member provides. ## Rule reference Each violation names one of these rules. The usual severity is shown, and a state can set it differently. | Rule | Usual severity | What it means | | - | - | - | | `required_designator` | `error` | The name lacks an ending the state accepts for this entity type, sub-form, or profession. | | `prohibited_word` | `error` | The name contains a word the state bars for this entity type. | | `restricted_word` | `needs_approval` | The name contains a word the state allows only with an agency's approval or a license. | | `character_limit` | `error` | The name is longer than the state allows. The limit is 255 characters, or lower where the state sets a lower one, such as 80 in Georgia. | | `character_set` | `error` | The name uses characters the state does not accept. | | `entity_type_unavailable` | `error` | The state does not allow this entity type, so no name is eligible for it. | | `professional_entity_required` | `advisory` | The name or the `profession` you passed signals a licensed profession that the state lets this entity type practice only as a professional entity. The message names the professional form to use. | | `profession_rules_not_checked` | `advisory` | The state sets professional names by profession, and those rules were not applied, because no `profession` was passed or the state records no rules for the one passed. | | `obscene_content`, `deceptive_agency_similarity`, `misleading_purpose` | `advisory` | Content concerns from screening. Returned only with `screen=true`. | ## Next steps Form a business Register a new LLC or corporation with any US state. [Open](/comply/form-a-business) Registry search Find a registered business by name, jurisdiction, or location. [Open](/onboard/registry-search) Check business name eligibility Full reference for the name-eligibility endpoint. [Open](/api-reference/v1/registry/check-business-name-eligibility) Get accepted name designators Full reference for the accepted-endings endpoint. [Open](/api-reference/v1/registry/get-accepted-name-designators) # Onboard overview Source: https://docs.getpalm.com/onboard/overview Find any registered US business and pull its record in real time from the primary source, so your customer does not have to type it. Onboard is the entry point. Every Palm workflow starts by finding the business, and everything downstream — verification, monitoring, filings — hangs off the record you pull here. ![Image showcasing registry search with two results](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/OnboardEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=302a1d45b54c4c8f7382d2853efb3005) *** ## How business records work Every business registered in the US files with an authority that publishes a record of it: legal name, entity type, formation date, jurisdiction, current status, registered agent, and in many places the officers and members. That record is public, and it is the one regulators and lenders rely on. What makes it hard to use is that there is no single place to read it. Each jurisdiction keeps its own system, with its own search, its own field names, and its own idea of what a business record contains. Palm reads those sources directly and normalizes what comes back: 125M US businesses, read in real time from the source rather than from a periodically refreshed copy, in one shape regardless of where the business is registered. Which means the record your customer is about to type into your application already exists, and Palm can hand it to you instead. They give you a name, pick their business out of the results, and the rest of your form fills from the record. Every field they do not have to type is a field they cannot get wrong. ## What Onboard does | Capability | What it does | | - | - | | [Registry search](/onboard/registry-search) | Find a registered business by name, jurisdiction, location, or identifier. | | [Registry detail](/onboard/registry-detail) | Pull everything Palm holds on the business. Prefill your application from it, and screen on standing. | | [Name eligibility](/onboard/name-eligibility) | Check whether a proposed name can be registered, before anyone commits to it. | ## When to use it * At the start of a relationship. Embed search in your application flow so a business is identified before it is underwritten, approved, or verified. * To enrich what you already hold. You have a name and need the registration number, address, or officers. * Before a formation. Check that a proposed name is available and compliant in the target jurisdiction. ## What comes next Onboard finds the business and returns its public record. It does not test what your customer told you, validate a tax ID against the IRS, or screen the people behind the business. Those are questions the public record cannot answer. ![Representation of how onboard falls within the Palm product suite.](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/GeneralPalmOutline.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=56b2ec60e41ae1af5d984b2d07ddfaa4) | Product | Role | | - | - | | Onboard | Find the business. Pull its record. | | Verify | Test what your customer told you, validate the tax ID, screen for risk. | | Monitor | Watch the record for changes over time. | | Comply | Act on the business. File, and write the result back. | ## Next steps Registry search Find a registered business by name, jurisdiction, or location. [Open](/onboard/registry-search) Registry detail Pull the full record, including connected people and standing. [Open](/onboard/registry-detail) Check name eligibility Check whether a prospective business name can be registered before filing a formation. [Open](/onboard/name-eligibility) Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) # Registry detail Source: https://docs.getpalm.com/onboard/registry-detail Pull everything Palm holds on a business: prefill your application from it, and screen on standing before you verify. [Registry search](/onboard/registry-search) identifies the business. Detail returns everything Palm holds about it. That is the point at which your member stops typing. The legal name, entity type, formation date, jurisdictions, addresses, registered agent, and the people on file all come back in one call, so the rest of your application fills itself from an authoritative record instead of from what someone remembers. And because the business now has a Palm ID, that identity is reusable: the same record carries into verification, monitoring, and filings without anyone entering it a second time. *** ## Retrieve a record ```bash Bash wrap theme={null} GET /v1/business/registry/{registration_jurisdiction}/{registration_number} ``` Both values come straight from a search result. A registration number is only unique within its jurisdiction, so the two are always used together. Every jurisdiction publishes its records differently. Palm normalizes them into one shape, so you read the same fields whether the business registered in Delaware or Wyoming. For the full response, see [Get business from registry](https://docs.getpalm.com/api-reference/v1/registry/get-business-from-registry). ## Prefill the application Most of what a business application asks for is already on the public record: the legal name, the jurisdictions the business was formed in and operates in, the formation date, the registered agent, and the officers, directors, and members on file. Ask your member for the one thing only they can tell you, and read the rest. Fewer fields mean fewer chances to mistype something, fewer abandoned applications, and data that already agrees with the source you would have checked it against. ## Screen before you verify The record also carries the entity's current status and its standing, broken out by category rather than as a single flag. In most jurisdictions that comes back with the record, in the same call, with no separate lookup and no government fee. That makes detail a cheap first gate. A business that comes back suspended, revoked, or behind on its obligations is worth catching before you spend anything on deeper checks. It may also be a problem you can resolve rather than a reason to reject. A business that comes back clean is worth those checks. ## Then verify You now have the business as the authoritative sources describe it. What you do not have is whether the tax ID your customer gave you belongs to this entity, whether the people signing up are who they say they are, or whether anything about them should stop the application. That is [Verify](/verify/overview). ## Next steps Verify a business Confirm the entity is real and registered, validate its tax ID, and screen for risk. [Open](/verify/verify-a-business) Registry search Find a business by name, jurisdiction, or location. [Open](/onboard/registry-search) Monitor overview Watch a business record for standing and registration changes. [Open](/monitor/overview) # Registry search Source: https://docs.getpalm.com/onboard/registry-search Find any registered US business by name, jurisdiction, or location, read in real time from the primary source. Search is how a business enters your flow. Your member types a name, Palm returns the registered entities that match, and they pick theirs. From that point you are working with a real record rather than typed input. ![Image showcasing registry search with two results](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/OnboardEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=302a1d45b54c4c8f7382d2853efb3005) *** ## What search is for Search answers one question: which registered business is this? Use it when you have a partial identity and need the real record behind it. * **Application forms.** A member picks their entity from results rather than typing a registration number they do not know. * **Type-ahead.** Resolve a name to a record while the member is still typing. * **Filling gaps.** You have a name but need the registration number, jurisdiction, or formation date. Search is a lookup, not a verification. It confirms a record exists and returns what the source holds. It does not assess risk, validate a tax ID, or screen against watchlists. That is [Verify](/verify/overview). ## Search for a business ```bash Bash wrap theme={null} POST /v1/business/registry/search ``` Search by name, identifier, jurisdiction, entity type, status, or location, in any combination. Each match comes back with a Palm ID, the core registration data, and the principal address on file. For every parameter and the full response shape, see [Search business registries](https://docs.getpalm.com/api-reference/v1/registry/search-business-registries). > [!NOTE] > > **Registration and formation jurisdiction are not the same thing.** A company can form in one state and register to do business in another. If you are unsure which to filter on, `registration_jurisdiction` is usually the one you want, because it is where the business actually operates. ## Narrowing results A common name can match a lot of entities. Filters are how you cut a broad result set down to something a member can pick from: jurisdiction first, then entity type or status. You also do not have to re-pull a record you already hold. Most partners cache results on their side with a freshness window that suits the flow, and refresh on their own schedule. ## Reading a result Two fields need a closer look. Status. This is the standing of the registration, not whether the company is trading. `active` means the business has kept up with its required filings and fees and is authorized to operate. A business that has fallen behind may come back `suspended` or `revoked`: it still exists, but it is not in good standing, and that is usually worth acting on. Registration number. The authority the business registered with assigns it. It is unique inside that jurisdiction but not across jurisdictions, so a registration number is only meaningful when paired with the jurisdiction it came from. ## Next: the full record Search returns enough to identify a business and show it in a picker. Pull the detailed record with the jurisdiction and registration number from the result, and you get everything Palm holds on that business: enough to prefill the rest of your application, and enough to screen on standing before you commit to deeper checks. See [Registry detail](/onboard/registry-detail). ## Next steps Registry detail Pull the full record for a business, including connected people and standing. [Open](/onboard/registry-detail) Check name eligibility Check whether a proposed business name can be registered, before anyone commits to it. [Open](/onboard/name-eligibility) Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) # Verify overview Source: https://docs.getpalm.com/verify/overview Verify businesses and people against authoritative sources. KYB, KYC, risk assessment, and ongoing re-verification. Verify is Palm's identity verification suite. It confirms that a business is real, registered, and in good standing — and that a person is who they claim to be. Palm verifies against authoritative sources and returns structured results: match data, risk assessment, and specific risk signals you can act on. ![Image showcasing a business risk score card, and the output of a verification request](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/VerifyOverviewEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=4524037c835cc4ca9b7e3e9fbdfa7408) *** ## What Verify does * **Verify a Business (KYB):** KYB stands for Know Your Business. Palm confirms that a business entity is real, registered, and in good standing by verifying against state registries, the IRS, and licensing agencies. Optionally verify beneficial owners in the same call. * **Verify a Person (KYC):** KYC stands for Know Your Customer. Palm confirms that a person is who they claim to be by verifying identity against authoritative sources, detecting synthetic (fabricated) identities, running velocity checks to catch fraud patterns, and screening against sanctions and watchlists. * **Verify a TIN:** Validate a TIN (EIN or SSN) and name against IRS records as a standalone check, without running a full business or person verification. ## Verification is ongoing Verification isn't just an onboarding step. Businesses change — ownership transfers, registrations lapse, compliance state shifts. Verify is designed for recurring use: * **At onboarding:** Verify a business and its people when they first arrive on your platform. * **On a schedule:** Re-verify annually, quarterly, or on whatever cadence your compliance requirements dictate. * **When triggered:** Re-verify in response to a change event, such as an officer update or ownership transfer detected through Monitor. Re-verification pulls from the latest data from your vault. One API call with just the business ID and workflow key. ## How it connects to Onboard Onboard is where you find businesses and pull their public record. Verify runs the checks that go beyond the public record - TIN validation, risk assessment, watchlist screening, and identity verification on associated people. A typical flow: ![Representation of how verify falls within the Palm product suite.](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/GeneralPalmOutline.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=56b2ec60e41ae1af5d984b2d07ddfaa4) Not every integration uses every step. You can use any combination of products depending on your needs. They work together but operate independently. ## From search to verification Every verification returns: * **Match results:** How each submitted field compares against authoritative records (`match`, `no_match`, `partial_match`, or `not_checked`). * **Risk assessment:** A risk level (`low`, `medium`, `high`, or `critical`) with specific risk signals that explain the assessment. * **Verification status:** `pending`, `in_progress`, `completed`, or `failed`. KYC adds synthetic identity detection, velocity checks, and watchlist screening. KYB adds associate (beneficial owner) verification results. For the full breakdown of risk levels, risk signals, and match result types, see [Verification Reference](/verify/verification-reference). ## Next steps Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) Verify a person Verify a person's identity with KYC checks, synthetic identity detection, and watchlist screening. [Open](/verify/verify-a-person) Verification reference Risk levels, risk signals, match results, and verification lifecycle details. [Open](/verify/verification-reference) Onboard overview Find and onboard businesses into your platform. [Open](/onboard/overview) # Verification reference Source: https://docs.getpalm.com/verify/verification-reference Risk levels, risk signals, match results, and verification lifecycle details. This page covers the shared concepts across all Palm verifications - risk levels, risk signals, match result types, and verification lifecycle. For quickstart guides and API examples, see [Verify a Business](/verify/verify-a-business) and [Verify a Person](/verify/verify-a-person). ![Image showcasing a business risk score card, and the output of a verification request](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/VerifyOverviewEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=4524037c835cc4ca9b7e3e9fbdfa7408) *** ## Verification lifecycle Verifications report one of these statuses: | Status | Description | | - | - | | `pending` | Verification created but not yet started. | | `in_progress` | Currently being processed. Most verifications complete in seconds. Cases that require enhanced due diligence are reviewed by our verification team. | | `completed` | Finished with results — check `risk.level` and `match` for details. A `completed` status does not mean the person or business "passed" — it means Palm has results for you to act on. | | `failed` | System error (provider unavailable, configuration issue). This is not a verification failure — it means something went wrong technically. Retry the request. | A verification can report `pending` or `in_progress` while work is underway, so use webhooks or retrieve the verification by its ID to get the final result. The flow: submit verification request, data validated against workflow requirements, entity/entities created and data stored in the vault, request sent, results returned with verification ID. ## Risk levels Every completed verification returns a risk level. This is Palm's overall assessment based on all signals combined. | Level | What it means | Typical action | | - | - | - | | `low` | No significant concerns detected. Identity data matches authoritative records, no watchlist hits, no fraud signals. | Approve. This is the happy path. | | `medium` | Minor concerns that warrant attention. Could be a partial name mismatch, a single CIP field that didn't match, or a low-confidence PEP hit. | Review recommended. In many cases these resolve to false positives — a name formatting difference, a recent address change. But they should be looked at. | | `high` | Serious concerns that require human review before proceeding. Triggers include confirmed synthetic identity flags, multiple field mismatches, or sanctions matches. | Manual review required. Do not auto-approve `high` risk verifications without human review. | | `critical` | Severe issues. The fraud score is in the highest tier, there are multiple compounding risk signals, or there's a confirmed sanctions match with high confidence. | Likely rejection. Critical risk almost always means the identity or business should not be onboarded without extraordinary justification. | ## Risk signals Risk signals are the specific indicators that drove the risk assessment. The `risk.reasons` array in the response contains the signals that contributed to the risk level. Examining individual signals — not just the overall level — is how you make informed decisions about borderline cases. ### Identity risks | Signal | What it means | Typical action | | - | - | - | | `watchlist_match` | A match was found on a sanctions or watchlist database. This is a general signal — check the `watchlist` object in the response for the specific list and confidence score. | Review the watchlist match details. Potential matches (low confidence) may be false positives due to common names. Confirmed matches require compliance team review. | | `sanctions_match` | OFAC SDN list or international sanctions match. This is the most serious identity signal — transacting with a sanctioned individual can carry severe legal penalties. | Escalate to compliance immediately. Do not proceed with onboarding until the match is reviewed and resolved. | | `pep_match` | Person identified as a Politically Exposed Person — someone who holds or recently held a prominent public function (elected officials, senior government employees, military leaders, judiciary). | PEP status alone isn't disqualifying. It means enhanced due diligence is required. Understand the person's role and assess whether the business relationship makes sense in context. | | `adverse_media` | Negative news coverage found related to the person — typically involving financial crime, fraud, regulatory action, or legal proceedings. | Review the specific media coverage. Adverse media is a contextual signal, not a definitive one. A news article about a dismissed lawsuit is different from coverage of an ongoing fraud investigation. | | `duplicate_identity` | The submitted identity matches another person already verified in your system. Same SSN, same DOB, but different name or other details. | Investigate whether this is a data entry error, a legitimate name change, or potential identity theft. | | `identity_theft_indicators` | The identity attributes show patterns consistent with stolen identity use — for example, the SSN belongs to a deceased person, or the identity shows signs of being used without the owner's knowledge. | High-priority review. Identity theft indicators require careful handling because there's a real victim involved. | ## Match results Match results indicate how well submitted data aligns with authoritative sources. Every verified field returns one of these values: | Result | What it means | | - | - | | `match` | The submitted value matches authoritative records. For names, this means an exact match. For addresses, minor formatting differences (e.g., "St" vs "Street") are normalized before comparison. | | `no_match` | The submitted value doesn't match what's on file. This is a negative signal, but severity depends on the field. An address `no_match` (people move) is less concerning than an SSN `no_match` (SSNs don't change). | | `partial_match` | The submitted value is close but not exact. Common causes: name variations ("Bob" vs "Robert"), hyphenated last names, address formatting differences, or minor typos. A `partial_match` is not a failure — it's a signal that something is close but not identical. | | `not_checked` | The field was not checked against authoritative sources. This typically means the provider doesn't have data for this field, or the field wasn't required by your workflow. | Only fields included in the verification request appear in match results. ## Vault storage Palm stores all submitted data in an encrypted vault at the time of verification. When you re-verify a person or business, Palm pulls from the vault. ## Workflows Every verification request includes a `workflow_key`. The workflow controls what happens when Palm processes a verification — which checks run, what fields are required, and how risk is assessed. ### What a workflow configures A workflow defines a sequence of automated checks. Depending on your configuration, a single verification request can trigger any combination of: | Check | What it does | | - | - | | Identity verification | KYC/KYB against authoritative sources. | | TIN verification | EIN or SSN validated against IRS records. | | Risk assessment | Evaluates risk signals and calculates an overall risk level. | ### Execution mode Workflows run in `headless` mode — the API call executes all checks and returns results synchronously. No user interaction required. You submit the verification request, Palm runs the configured checks, and you get results back in one response. ### How to get a workflow key Palm configures workflows based on your compliance requirements. During onboarding, we'll set up one or more workflows tailored to your use case — the checks you need, the fields you require, and the risk thresholds that match your program. You'll receive a `workflow_key` for each configuration. If your requirements change (e.g., you need to adjust required fields), reach out and we'll update your workflow configuration. A self-service workflow configurator is available in Palm Console (beta). [Contact us](mailto:support@getpalm.com) for access. ## Webhooks Verification completion fires webhook events: | Event | Description | | - | - | | `user.verification.completed` | KYC verification finished. | | `business.verification.completed` | KYB verification finished. | Webhook payloads include the verification ID, risk level, and summary match results. Subscribe to webhooks for async notification rather than polling. See [Webhooks](/developer-guide/webhooks). ## Best practices * **Handle all risk levels:** Implement logic for `low`, `medium`, `high`, and `critical` outcomes. Don't just handle the happy path. * **Use risk signals:** Examine individual signals in `risk.reasons`, not just the overall risk level. Two verifications can both be `medium` risk for very different reasons — a PEP match requires different handling than a data mismatch. * **Verify associated people:** For businesses, verify owners with significant ownership by including them as associates. Regulatory frameworks typically require verification of anyone with 25%+ ownership or significant control. * **Subscribe to webhooks:** Use async notification rather than polling for verification completion. * **Log verification IDs:** Store verification IDs for audit trail and support. You'll need them for compliance reporting and dispute resolution. * **Review match results:** Use field-level match data to understand verification confidence. A verification with `low` risk but several `partial_match` results is less confident than one with all `match` results. ## Next steps Verify a person Verify a person's identity with KYC checks, synthetic identity detection, and watchlist screening. [Open](/verify/verify-a-person) Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) Monitor Enroll verified businesses in ongoing monitoring. [Open](/monitor/overview) Onboard overview Find and onboard businesses into your platform. [Open](/onboard/overview) # Verify a business Source: https://docs.getpalm.com/verify/verify-a-business Confirm that a business entity is real, registered, and in good standing. Business verification (KYB, Know Your Business) confirms that an entity exists, is registered with the appropriate government authorities, and is currently in good standing. Palm verifies against authoritative sources (state registries, the IRS, and licensing agencies) and returns structured results you can act on. ![Image showcasing a form to collect information, and the output of a verification request](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/VerifyBusinessEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=53c6abc44019878605df2d36cb7d2e1b) *** ## What business verification checks When you verify a business, Palm runs several checks against authoritative sources: * **State Registry verification:** Palm queries the Secretary of State (SOS) office where the business is registered. This confirms the business exists, checks that its registration is active (not dissolved, suspended, or revoked), and validates details like the legal name, entity type, and formation date. A business that hasn't filed its annual report or paid its state fees will show as out of compliance. * **EIN verification:** The Employer Identification Number is assigned by the IRS and serves as the business's tax ID. Palm verifies the EIN against IRS records to confirm the number matches the business name. This catches cases where a business submits someone else's EIN, uses a recently issued number that hasn't propagated yet, or provides an EIN that doesn't correspond to any business on file. * **Associate verification:** If you include associates in the request, each one undergoes individual person verification: identity checks, synthetic identity detection, and watchlist screening for every person with significant ownership or control. See [Verify a Person](/verify/verify-a-person) for what it covers. ## What you get back When you verify a business, Palm returns: * **Match results:** How each submitted field compares against authoritative records (`match`, `no_match`, `partial_match`, or `not_checked`). * **Risk assessment:** A risk level (`low`, `medium`, `high`, or `critical`) with specific risk signals that explain the assessment. * **Associates:** If beneficial owners are included, each undergoes individual KYC verification. * **Verification status:** `pending`, `in_progress`, `completed`, or `failed`. For the full breakdown of risk levels, risk signals, and match result types, see [Verification Reference](/verify/verification-reference). ## Understanding the detail response | Field | Description | | - | - | | `business_id` | Palm's identifier for the verified business. Use this for subsequent API calls — re-verification, monitoring enrollment, and Registry lookups. | | `verification_id` | Unique identifier for this specific verification run. A single business can have multiple verifications over time (initial verification, annual re-verification, triggered re-verification). Each gets its own ID. | | `status` | Where the verification is in its lifecycle. `completed` means results are ready. `failed` means a system error occurred (not a verification failure) — retry the request. See [Verification Reference](/verify/verification-reference) for all statuses. | | `mode` | `test` or `live` — which partition the verification ran in, determined by the API key used. | | `risk.level` | Overall risk assessment: `low`, `medium`, `high`, or `critical`. See [Verification Reference](/verify/verification-reference) for what each level means and how to handle it. | | `risk.reasons` | Array of specific risk signals that explain the assessment. An empty array with `low` risk means nothing concerning was detected. A high risk with `["shell_company_indicators", "newly_registered"]` tells you exactly why. See [Verification Reference](/verify/verification-reference) for all signal types. | | `match` | Field-level match results. Only fields you included in the request appear here. `match` means the value you submitted matches authoritative records exactly. `no_match` means it doesn't. `partial_match` means it's close but not exact — common with address formatting differences or minor name variations. | | `associates` | Array of individual KYC verification results for each beneficial owner. Each associate gets the full KYC treatment: identity matching, synthetic identity detection, and watchlist screening. | ## Match fields KYB verification can return match results for these fields: | Field | Description | | - | - | | `legal_name` | Whether the submitted name matches the name on file with the state. Minor variations (e.g., "Inc." vs "Incorporated") may return `partial_match`. | | `ein` | Whether the EIN matches IRS records for this business. A `no_match` here is a strong negative signal — it means the business either submitted the wrong EIN or the EIN belongs to a different entity. | | `entity_type` | Whether the legal structure matches state records. Catching a mismatch here matters — if someone claims to be a Corporation but the state has them as an LLC, that's either an error or a red flag. | | `registration_jurisdiction` | Whether the business is registered in the state it claims. | | `formation_jurisdiction` | Whether the business was formed in the jurisdiction it claims. | | `formation_date` | Whether the incorporation date matches. Newly formed businesses (within the last few months) may not yet appear in all state databases. | | `address_line_1` | Whether the street address matches state records. Businesses frequently move without updating their state filing, so an address mismatch is relatively common and not always a concern. | | `city` | City match. | | `region` | State match. | | `postal_code` | ZIP code match. | > [!NOTE] > > Only fields included in the verification request appear in match results. For match result types and risk level details, see [Verification Reference](/verify/verification-reference). ## When to use Use business verification when a business entity first interacts with your platform: during onboarding, before extending credit, or before binding a policy. Use it again when compliance state changes or on a recurring schedule. If you also need to verify the person behind the business, follow this call with person verification. Or include associates in the request to verify beneficial owners in the same call. ## Quickstart **Prerequisites** * A Palm API key: [Get access](/get-started/get-access) * The business's legal name and state/region ### Verify a business Send a `POST` request to `/v1/business/verification`: ```bash Bash wrap theme={null} curl -X POST https://api.getpalm.com/v1/business/verification \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer sk_test_...' \ -d '{ "workflow_key": "business_verification_default", "legal_name": "Acme Corporation", "region": "US-CA" }' ``` The minimum request requires a `workflow_key`, `legal_name`, and `region`. You can improve match accuracy by including additional fields like `ein`, `entity_type`, `formation_jurisdiction`, `address`, and `associates` (beneficial owners to verify inline). For the full parameter reference, see the [API Reference](/api-reference/introduction). You can also verify people as part of a business verification by including them as associates. See [Verify a Person](/verify/verify-a-person). ### Response A successful verification returns match results, risk assessment, and, if associates were included, individual KYC results for each owner: ```json JSON wrap theme={null} { "business_id": "987e6543-e21a-45b6-c789-012345678901", "verification_id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "mode": "test", "risk": { "level": "low", "reasons": [] }, "match": { "legal_name": "match", "region": "match", "ein": "match" }, "associates": [ { "user_id": "123e4567-e89b-12d3-a456-426614174000", "verification_id": "660f9511-f30c-52e5-b827-557766551111", "status": "completed", "mode": "test", "risk": { "level": "low", "reasons": [] }, "match": { "first_name": "match", "last_name": "match", "date_of_birth": "match", "ssn": "match" }, "watchlist": { "status": "clear" }, "created_at": "2026-01-15T10:30:00Z" } ], "created_at": "2026-01-15T10:30:00Z" } ``` ## Re-verification Existing businesses can be re-verified without resubmitting data. Palm retrieves the current data from the vault and runs verification against stored values: ```bash Bash wrap theme={null} curl -X POST https://api.getpalm.com/v1/business/987e6543-e21a-45b6-c789-012345678901/verification \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer sk_test_...' \ -d '{ "workflow_key": "business_verification_default", "reference_id": "reverify_12345" }' ``` Re-verification is useful on a recurring schedule (annual compliance reviews) or when triggered by a monitoring event (a state registration lapsing, an adverse media hit). ## Retrieve a verification Fetch a completed verification by its `business_id` and `verification_id`, useful for pulling the current status and results without waiting on a webhook, or for re-reading a past run: ```bash Bash wrap theme={null} curl https://api.getpalm.com/v1/business/987e6543-e21a-45b6-c789-012345678901/verification/550e8400-e29b-41d4-a716-446655440000 \ -H 'Authorization: Bearer sk_test_...' ``` The response is the same shape returned when the verification was created: status, risk assessment, match results, and any associates. ## Webhooks Subscribe to `business.verification.completed` to receive async notification when a verification finishes. Webhook payloads include the verification ID, risk level, and summary match results. ## Next steps Verify a person Verify a person's identity with KYC checks, synthetic identity detection, and watchlist screening. [Open](/verify/verify-a-person) Verification reference Risk levels, risk signals, match results, and verification lifecycle details. [Open](/verify/verification-reference) Start monitoring Track changes to verified businesses in real time. [Open](/monitor/overview) Search the Registry Search all US registered businesses in the network by name, jurisdiction, or location. [Open](/onboard/registry-search) # Verify a person Source: https://docs.getpalm.com/verify/verify-a-person Run KYC identity verification with name, DOB, SSN, and address checks, synthetic identity detection, velocity signals, and sanctions screening. Person verification (KYC: Know Your Customer) confirms that an individual is who they claim to be. Palm verifies identity against authoritative sources, detects synthetic identities, runs velocity checks, and screens against sanctions and watchlists. ![Image showcasing a form to collect information, and the output of an user verification request](https://mintcdn.com/palmfinance/1RPIbiD5PV2g0B_e/images/VerifyPersonEyeCatch.webp?fit=max\&auto=format\&n=1RPIbiD5PV2g0B_e\&q=85\&s=65191107bac41e19573bc609c84cb478) *** ## What KYC verification checks * **Identity matching:** Palm compares the submitted name, date of birth, SSN, and address against authoritative sources. Each field is checked independently, so you get granular results: you'll know if the name matched but the address didn't. * **Synthetic identity detection:** A synthetic identity is a fabricated identity built by combining real and fake data. A fraudster might pair a real SSN (often belonging to a child, elderly person, or recent immigrant) with a fake name and address. These identities can pass basic checks because some of the data is real. Palm detects synthetic identities by analyzing patterns across identity attributes that indicate fabrication. * **Velocity checks:** Palm tracks how frequently identity attributes appear across recent verifications. If the same SSN shows up in different verification requests in a week, that could be a strong fraud signal, even if each individual verification looks clean. Velocity checks catch patterns that point-in-time checks miss, including application fraud rings and credit stacking (rapidly applying for credit across multiple lenders). * **Watchlist screening:** Palm screens against sanctions lists (OFAC SDN list and international equivalents), Politically Exposed Person (PEP) databases, and adverse media sources. A sanctions match means the person appears on a government list of individuals with whom financial transactions are restricted or prohibited. A PEP match means the person holds (or recently held) a prominent public function. PEPs aren't necessarily risky, but they require enhanced due diligence under most compliance frameworks. ## What you get back * **Match results:** How each submitted field compares against authoritative identity records (`match`, `no_match`, `partial_match`, or `not_checked`). * **Risk assessment:** A risk level (`low`, `medium`, `high`, or `critical`) with specific risk signals that explain the assessment. * **Synthetic identity detection:** Whether Palm detects indicators of a fabricated identity. * **Velocity checks:** How frequently identity attributes appear across recent verifications, surfaced as risk signals in `risk.reasons` rather than a separate field. * **Watchlist screening:** Sanctions, PEP, and adverse media results. * **Verification status:** `pending`, `in_progress`, `completed`, or `failed`. ## When to use this Use person verification during onboarding, before extending credit, or when confirming authorized signers. Common scenarios: verifying beneficial owners, confirming officers during underwriting, or validating authorized representatives. You can also verify people as part of a business verification by including them as associates. See [Verify a business](/verify/verify-a-business). ## Quickstart **Prerequisites** * A Palm API key: [Get access](/get-started/get-access) * The person's name, date of birth, SSN, and address ### Verify a person Send a `POST` request to `/v1/user/verification`: ```bash Bash wrap theme={null} curl -X POST https://api.getpalm.com/v1/user/verification \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer sk_test_...' \ -d '{ "workflow_key": "user_verification_default", "first_name": "Jane", "last_name": "Smith", "date_of_birth": "1985-03-15", "ssn": "123-45-6789", "address_line_1": "100 Main Street", "city": "San Francisco", "region": "CA", "postal_code": "94105" }' ``` ### Request fields The minimum request requires a `workflow_key`, the person's name, date of birth, SSN, and address. This runs core identity matching. Beyond that, send every identity field you collect: optional fields each unlock additional fraud checks, so the more you send, the more complete the assessment. If a check's input isn't provided, that check simply doesn't run: a missing input is **not** treated as a risk factor and won't appear in `risk.reasons`. #### Optional fields and what they unlock | Field | What it adds | | - | - | | `phone_number` | Enables identity-theft risk scoring. If omitted, that check doesn't run and isn't counted for or against the result. | | `email` | Adds email-based fraud and velocity signals. | | `ip_address` | Adds device/connection risk signals (session-based verifications). | If your workflow is tuned for a specific field set and you're unsure what to send, [contact us](mailto:support@getpalm.com). We'll align your workflow with the data you collect. For the full field reference, types, and validation rules, see the [API Reference](/api-reference/introduction). ### Response A successful verification returns match results, risk assessment, and - if associates were included - individual KYC results for each owner: ```json JSON wrap theme={null} { "user_id": "550e8400-e29b-41d4-a716-446655440000", "verification_id": "660f9511-f30c-52e5-b827-557766551111", "status": "completed", "mode": "test", "risk": { "level": "low", "reasons": [] }, "match": { "first_name": "match", "last_name": "match", "date_of_birth": "match", "ssn": "match", "address_line_1": "match", "city": "match", "region": "match", "postal_code": "match" }, "synthetic": { "is_synthetic": false, "confidence_score": 12 }, "watchlist": { "status": "clear" }, "created_at": "2026-01-15T10:30:00Z" } ``` ### Understanding the response | Field | Description | | - | - | | `user_id` | Palm's identifier for the verified person. Use this for re-verification and audit trails. | | `verification_id` | Unique identifier for this verification run. | | `status` | Where the verification is in its lifecycle. `completed` means results are ready. `failed` means a system error occurred — retry the request. See [Verification Reference](/verify/verification-reference) for all statuses. | | `mode` | `test` or `live` — which partition the verification ran in, determined by the API key used. | | `risk.level` | Overall risk assessment: `low`, `medium`, `high`, or `critical`. The level reflects the verification outcome — an identity that can't be verified against authoritative sources is elevated rather than returned as `low`. It also escalates on watchlist hits, synthetic-identity flags, field match failures, and address or identity red flags (for example a commercial or mail-drop address, no established history at the address, multiple identities tied to one address, or a thin identity history). | | `risk.reasons` | The genuine risk factors that drove the assessment. An empty array means none were found — read it alongside `risk.level`. Checks that couldn't run because an optional input wasn't provided are **not** listed here. Example: `["identity_theft_indicators", "high_fraud_score"]`. | | `synthetic.is_synthetic` | Whether Palm detected indicators of a fabricated identity. `true` automatically escalates risk significantly. | | `synthetic.confidence_score` | Score from 0–100. Higher means more likely synthetic. Scores above 50 are concerning; above 70 are strong indicators of fabrication. | | `watchlist.status` | `clear` means no matches. `potential_match` means a possible hit that needs review. `confirmed_match` means a definitive match against a sanctions, PEP, or adverse media list. `not_screened` means screening did not run. | ### Watchlist matches When `watchlist.status` is `potential_match` or `confirmed_match`, the response includes match details: ```json JSON wrap theme={null} { "watchlist": { "status": "potential_match", "matches": [ { "type": "pep", "name": "tauxbe", "confidence_score": 72 } ] } } ``` Each match includes a `type`: * **`sanctions`:** OFAC SDN list and international sanctions lists. A confirmed sanctions match means you likely cannot do business with this person under US law. This is the most serious watchlist result. * **`pep`:** Politically Exposed Person. The person holds or recently held a prominent public function. A PEP designation doesn't mean the person is risky. It means enhanced due diligence is required under most regulatory frameworks. * **`adverse_media`:** Negative news coverage related to financial crime, fraud, or regulatory action. Adverse media hits provide context for risk decisions but aren't definitive on their own. They require human review. The `confidence_score` (0–100) indicates how closely the watchlist record matches the submitted identity. Scores above 90 are high-confidence matches. **Name-only matches.** PEP and adverse-media hits matched on name alone, without date-of-birth corroboration, are reported as `potential_match` with a confidence score rather than as confirmed matches, and don't inflate the risk level. This keeps common names from triggering false positives. Sanctions matches are treated as high priority. ## Match fields KYC verification can return match results for these fields: | Field | Description | | - | - | | `first_name` | Legal name only — "Bob" won't match "Robert" and will return `no_match` or `partial_match`. | | `last_name` | Hyphenated names and name changes (marriage) can cause `partial_match` results. | | `middle_name` | Middle name, if provided. | | `date_of_birth` | A `no_match` on DOB is a strong negative signal — dates of birth rarely have legitimate data entry errors. | | `ssn` | An SSN `no_match` is the strongest single negative signal — it means the SSN either doesn't exist, belongs to someone else, or was recently issued and hasn't propagated to all sources. | | `email` | Email match against known identity records. | | `phone_number` | Phone number match. | | `address_line_1` | Street address. People move frequently, so an address `no_match` on its own is less concerning than SSN or DOB mismatches. | | `city` | City match. | | `region` | State/region match. | | `postal_code` | ZIP code match. | Only fields included in the verification request appear in match results. For match result types and risk level details, see [Verification Reference](/verify/verification-reference). ## Re-verification Existing users can be re-verified by passing the `user_id`. Palm retrieves the current data from the vault and runs verification against stored values: ```bash Bash wrap theme={null} curl -X POST https://api.getpalm.com/v1/user/550e8400-e29b-41d4-a716-446655440000/verification \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer sk_test_...' \ -d '{ "workflow_key": "user_verification_default", "reference_id": "reverify_67890" }' ``` Re-verification is useful when compliance requirements change, when there's a suspicious identity signal, or on a scheduled basis. ## Retrieve a verification Fetch a completed verification by its `user_id` and `verification_id`, useful for pulling the current status and results without waiting on a webhook, or for re-reading a past run: ```bash Bash wrap theme={null} curl https://api.getpalm.com/v1/user/550e8400-e29b-41d4-a716-446655440000/verification/660f9511-f30c-52e5-b827-557766551111 \ -H 'Authorization: Bearer sk_test_...' ``` The response is the same shape returned when the verification was created: status, risk assessment, match results, synthetic-identity detection, and watchlist screening. ## Webhooks Subscribe to `user.verification.completed` to receive async notification when a verification finishes. Webhook payloads include the verification ID, risk level, and summary match results. ## Next steps Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) Verification reference Risk levels, risk signals, match results, and verification lifecycle details. [Open](/verify/verification-reference) Start monitoring Track changes to verified businesses in real time. [Open](/monitor/overview) Onboard overview Find and onboard businesses into your platform. [Open](/onboard/overview) # Verify a TIN Source: https://docs.getpalm.com/verify/verify-a-tin Validate a Tax Identification Number against IRS records — standalone, without a full business or person verification. ![Image showcasing a form to collect information, and the output of a TIN verification request](https://mintcdn.com/palmfinance/rX2qdY1PO1DEWy8L/images/VerifyTinEyeCatch.webp?fit=max\&auto=format\&n=rX2qdY1PO1DEWy8L\&q=85\&s=747ca7735bf15b031f3d7a42030441d3) *** ## What it does Verify TIN checks whether a TIN (EIN or SSN) matches the name on file at the IRS. It returns one of three results: matched, not matched, or pending (IRS unavailable). This is a single-purpose check. It does not run registry lookups, risk assessment, or any other verification step. If you need the full suite of business verification checks, use [Verify a Business](/verify/verify-a-business), which includes TIN verification as part of the workflow. ## When to use it Use the standalone TIN endpoint when you need to validate a TIN outside of a full verification flow: * **1099 processing:** Confirm TINs before filing to avoid IRS B-notices. * **Pre-verification validation:** Check a TIN before running a full business verification. * **Bulk TIN hygiene:** Validate TINs across your existing portfolio. * **SSN verification:** Validate an individual's SSN and name against IRS records, independent of a person verification. ## Request `POST /v1/tin/verification` | Field | Type | Required | Description | | - | - | - | - | | `tin` | string | Yes | EIN (`XX-XXXXXXX` or 9 digits) or SSN (`XXX-XX-XXXX` or 9 digits) | | `name` | string | Yes | For EIN: legal business name. For SSN: full name (`First Last` or `First Middle Last`) | | `tin_type` | enum | Yes | `ein` or `ssn` — determines the validation path | | `reference_id` | string | No | Your reference ID, echoed back in the response | | `metadata` | object | No | Free-form key/value pairs stored on the verification record | #### Example request ```bash wrap Bash theme={null} curl -X POST https://api.getpalm.com/v1/tin/verification \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer sk_test_...' \ -d '{ "tin": "12-3456789", "tin_type": "ein", "name": "Acme Corporation", "reference_id": "tin_req_12345" }' ``` ## Response | Field | Type | Description | | - | - | - | | `verification_id` | string (UUID) | Unique identifier for this TIN verification. | | `object` | string | Always `tin_verification`. | | `tin_type` | enum | `ein` or `ssn` (echoes the request). | | `matched` | boolean or null | `true` = match, `false` = no match, `null` = could not be determined. | | `status` | enum | `completed`, `pending`, `in_progress`, or `failed`. | | `unavailable_reason` | enum | Only present when `status` is `pending`. See below. | | `reference_id` | string | Echoed from request, if provided. | | `verified_at` | datetime | When the TIN was verified. Only present when `status` is `completed`. | ### Response states **Completed:** The IRS returned a definitive answer. Check `matched` for the result. ```json wrap JSON theme={null} { "verification_id": "550e8400-e29b-41d4-a716-446655440000", "object": "tin_verification", "tin_type": "ein", "matched": true, "status": "completed", "reference_id": "tin_req_12345", "created_at": "2026-04-22T05:33:01.665Z", "verified_at": "2026-04-22T05:33:01.665Z" } ``` **Pending:** The IRS TIN matching service is temporarily unavailable. `matched` is `null`. Check `unavailable_reason` and retry later. ```json wrap JSON theme={null} { "verification_id": "550e8400-e29b-41d4-a716-446655440000", "object": "tin_verification", "tin_type": "ein", "matched": null, "status": "pending", "unavailable_reason": "tin_matching_service_unavailable", "reference_id": "tin_req_12345", "created_at": "2026-04-22T05:33:01.665Z" } ``` ### Unavailable reasons | Reason | What it means | | - | - | | `tin_matching_service_unavailable` | IRS TIN matching service is temporarily down. Retry later. | ### Error codes | Reason | What it means | | - | - | | `tin_matching_invalid_format` | The TIN format was rejected by the IRS service. Check the input. | ## Handling IRS downtime The IRS TIN matching service has scheduled and unscheduled downtime. When the service is unavailable, the endpoint returns `status: pending` with `matched: null` instead of failing. This lets you distinguish between "TIN didn't match" (`matched: false`) and "we couldn't check" (`matched: null`). Build your integration to handle the pending state: store the `verification_id`, and retry when your system is ready. Do not treat `matched: null` as a match or a non-match. ## Verify TIN vs full business verification | | Verify TIN | Verify a Business | | - | - | - | | Endpoint | `POST /v1/tin/verification` | `POST /v1/business/verification` | | What it checks | TIN + name against IRS only. | Registry, TIN, risk, watchlists and more. | | Requires workflow | No. | Yes (`workflow_key`). | | Requires vault record | No. | Yes (business must exist in vault). | | Use case | Standalone TIN validation. | Full KYB verification. | For the full parameter reference, see the [API Reference](/api-reference/introduction). ## Next steps Verify a business Confirm that a business entity is real, registered, and in good standing. [Open](/verify/verify-a-business) Verification reference Risk levels, risk signals, match results, and verification lifecycle details. [Open](/verify/verification-reference) Start monitoring Track changes to verified businesses in real time. [Open](/monitor/overview) Onboard overview Find and onboard businesses into your platform. [Open](/onboard/overview)