Creating a Jurisdiction Registration
Overview
To request a tax Registration Form via the Middesk API, we recommend an implementation based on this flow.
1. Search Tax Jurisdictions
Requesting a registration requires a Jurisdiction so hit this endpoint to search for the Jurisdiction needed. From the payload response, grab the slug field from the respective necessary jurisdictions. This will be used
The scope of what a jurisdictions can be encompassed ranges from the local level such as a city up to the state level such as for Unemployment Insurance or Withholding.
2. Create Tax Registration
Hit this endpoint in order to create the form to send over to the end company.
- End employer will use the invite_link provided and complete the Middesk intake flow.
- The Submission of the Registration Request will generate "Jurisdiction Registrations" on the Middesk side which are registrations with a specific jurisdiction.
This endpoint requires company info such as email and name, and the chosen state / jurisdictions. Here you can pass in the slug found in Step (1) to the jurisdictions field to specify what jurisdictions the tax registration will be created for.
NOTE:
If nothing is passed into the jurisdictions field: By default, Middesk will create a Registration Request for all Unemployment/Withholding registrations in the given state.
2a) To view info about the registration request
Hit this endpoint to get any current info about the registration request manually such as the status.
3. Create a webhook to listen to updates for a Registration
Follow this API Reference for more info on how to build out the webhook to get up to date information immediately in your systems.
Glossary
Registration Request Statuses
| Status | Description |
|---|---|
| pending | Registration Request has been created but employer has not completed Middesk intake flow. |
| submitted | Employer has completed Middesk intake flow and Middesk or Government is processing registration. |
| completed | All requested deliverables from request are in a terminal status. |
| cancelled | Employer indicated during Middesk intake flow that they would not be submitting. |
Jurisdiction Registration Response
| Key | Description |
|---|---|
| id | unique identifier of Jurisdiction Registration |
| registration_request_id | ID referencing Registration Request this registration was a result of |
| status | current status of Jurisdiction Registration (see possible statuses below) |
Jurisdiction Registration Status
| Status | |
|---|---|
| information_requested | Jurisdiction registration requires additional information from the customer before processing can continue |
| blocked_by_government | Jurisdiction registration is blocked by government requirements (e.g., waiting for hire date, payroll date, or liability date) |
| middesk_processing | Jurisdiction registration is being processed by Middesk staff |
| government_processing | Jurisdiction registration has been submitted to the government and is being processed by the government |
| completed | Jurisdiction registration has been completed and Tax Registration Items are available |
| duplicate | Jurisdiction registration and corresponding Tax Registration Items were marked as duplicate as the company's information was already registered with the state/local government |
| unmanaged | Jurisdiction registration is not currently supported by Middesk |
| not_required | Jurisdiction registration is deemed by the government as not required for this business in this jurisdiction |
Updated about 11 hours ago