There are 2 ways to create a Registration Request for your Employers:
- If the employer company has not yet been added to Middesk
- If the employer company has already been added to Middesk (from a previous Registration Request)
Option 1:
If the employer company has not yet been added you will need to supply the "company_name" as a param to the API request. We will create a Child Company under your Partner account and return the "company_id" in the successful Registration Request response. You may also supply and optional "external_id" which you would then be able to use in future registration requests to create under the same child company.
Option 2:
If the employer company has already had a Registration Request added to it in Middesk you can simply provide the "company_id" as a param to the API request and the new Registration Request will be added to the same company as before. Also, if you supplied an "external_id" on the initial create API call for the child company you can just provide that instead of "company_id" to create Registration Requests on an existing child company. If there are multiple active Registration Requests for this company the employer will be prompted to complete all of them from the invite_link sent.
Upon success (201) the employer will receive an email from Middesk with the link to complete the Registration Request.
In order to track the Registration Request's lifecycle you can register to receive Registration Request Webhooks.
API Response Keys
| API Response Key | Description |
|---|---|
| id | Middesk Registration Request ID. Used to match incoming Registration Request Webhooks. |
| state | US State Abbreviation which Tax Registration was requested for. Example: "CA" |
| company_id | Middesk Company ID. ID of Company that this Registration Request was created for. Supplied by params "company_id" or if new "company_name" is provided resulting ID of created Middesk Company. This ID can be used in future Registration Requests in order to add to the same child company. |
| external_id | External ID of Company that was provided on Middesk Company creation. This ID should map to the ID of the Company/Employer in your system. |
| invite_link | Link sent to Employer to complete Registration Request. Upon successful Registration Request create call (201) Middesk will send the provided employer (email) this link to complete requested registrations. Note: This Link will expire 60 days after creation. |
| created_at | ISO 8601 UTC Timestamp when Registration Request was created by partner. Example: "YYYY-MM-DDTHH:MM:SSZ" |
| tax_registration_types | An array of strings representing the Tax Registration types requested for the given state. If value is null, Middesk will register all possible tax types in that state. Example: ["state_unemployment_insurance", "state_tax_withholdings".] |