Cookbook
File a foreign qualification
Register an existing entity to do business in a second state — agent, certificate of good standing, qualifying tax accounts.
Last updated
Register an existing entity to do business in a second state — agent, certificate of good standing, qualifying tax accounts.
Trigger
You're hiring or signing leases in a state that's not your state of incorporation.
Call sequence
1. Qualify
POST /v1/entities/{id}/qualify { state }2. Open employer registrations as needed
POST /v1/state_registrations { entity, state, kinds: ['withholding','sui'] }Idempotency
Qualification idempotent on `(entity, state)`.
Webhooks
| Event | Description |
|---|---|
qualification.completed | Registered to do business. |
state_registration.opened | Per registration. |
Errors
| Status | Code | Description |
|---|---|---|
422 | name_conflict_in_state | Existing entity in target state has the same name. Provide a DBA. |
Related
Variations
If your law firm or operations team provides registered-agent service:
{
"jurisdiction": "US-CA",
"registered_agent": {
"provider": "self",
"name": "Acme Compliance LLC",
"address": {
"street_1": "1 Market St, Suite 300",
"city": "San Francisco",
"region": "CA",
"postal_code": "94105",
"country": "US"
}
}
}If your legal name conflicts with an existing entity in the foreign state, file under a "doing business as" name:
{
"jurisdiction": "US-CA",
"registered_agent": {"provider": "matter"},
"dba_name": "Waypoint Systems CA"
}There's no batch endpoint — issue one call per jurisdiction with distinct
Idempotency-Keys. Run them in parallel:
const states = ["US-NY", "US-CA", "US-TX"];
await Promise.all(states.map(jurisdiction => qualify(jurisdiction)));Each fires its own webhook stream; subscribe with care to avoid alert noise.
Withdrawing from a state when you stop doing business there:
curl -X POST https://api.mattermode.com/v1/qualifications/qal_NY/withdraw \
-H "Authorization: Bearer $MATTER_KEY" \
-H "Matter-Version: 2026-05-01" \
-H "Idempotency-Key: $(uuidgen)"The cascade files the Certificate of Withdrawal, terminates the registered agent contract, and removes the foreign state from the compliance calendar.
FAQ
Related
- Register a state employer — withholding + SUI registrations
- Qualifications endpoint — primitive
- File all due reports — sweep per-state annual reports