How mode is set
Every request runs in exactly one mode, determined by the API key you authenticate with:
Create both key types in Palm Console, 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 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.
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.
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 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 samefiling.* 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 tocompleted. Set the reserved _simulate key in the filing’s metadata on the create request to drive a specific outcome. The value is <terminal>[:case_<status>][:auto].
Terminal outcome
Simulating an information request
Append
:case_<status> to open a case when the filing reaches that status — mirroring Palm needing more information from you before the filing can continue. <status> 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.
JSON
_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-levelmode field (test for sandbox events) so your handler can assert it.
See 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:- Replace your
sk_test_key with ansk_live_key from Console. - Register your live webhook endpoints (test endpoints do not receive live events).
- 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.