Partner - Cohosted API Integration

We suggest using the Cohosted API Integration as the first step for Partners new to the Middesk ecosystem to get started.

The Cohosted API Integration connects closely with the Partner dashboard to allow you to monitor requests both via API and from the dashboard.

A "Registration Request" represents a single request for an employer to submit information to complete a single state tax registration.

The following are the possible "statuses" of a Registration Request:

status	description
pending	Registration Request has not yet been submitted by your employer.
submitted	Registration Request has been submitted by your employer but not all Registration Items have been completed.
completed	Registration Request has been submitted and all Registration Items are marked as completed. Tax IDs are available for export.

API Key

To get started with the Cohosted API integration and begin making API requests to Middesk you must first acquire your API key from your Partner dashboard.

Go to your "Account" > "Settings" from the upper-right navigation.
Go to the "Credentials" page from the left sidebar navigation under "DEVELOPERS".
From there you should see your "Live API Key" listed. Take note of the value under "API Key".

API Endpoints

Create Registration Request

There are 2 ways to create a "Registration Request"

If you already have a child account created under your partner account in Middesk
If you would like to also create a brand new child account for this new Registration Request.

Both requests share mostly the same parameters:

param	description
email [required]	Child Account user email who will receive an email with a link to complete the Registration Request.
state [required]	Two character abbreviation of the US State to create the Registration Request for.
tax_registration_types [optional]	List of the types of registrations you would like the user to complete. Can be left blank for "All applicable registrations in state". Possible values are: ['state_unemployment_insurance'] or ['state_tax_withholdings']

Option 1 (Existing Child Account)

When adding a “Registration Request” onto an existing child account you must also provide the Middesk “Company ID” of the child account as an input parameter. This ID will be available on the response of any newly created child accounts for you to save and reuse.

Example:

curl https://api.middesk.com/v1/partner/registration_requests \
  -X POST \
  -u mk_live_2b7dc3728c80f8c278596ba9: \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "state": "AK",
    "company_id": "123-middesk-company-id"
  }'

Option 2 (New Child Account)

When adding a “Registration Request” to a new child account you must also provide the “Company Name” you would like to use for this employer. The response from creating this Child Account and Registration Request will have the “Middesk Company ID” for you to use if you want to request other Registrations on the same Child Account.

Example:

curl https://api.middesk.com/v1/partner/registration_requests \
  -X POST \
  -u mk_live_2b7dc3728c80f8c278596ba9: \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "state": "DC",
    "tax_registration_types: ["state_unemployment_insurance"],
    "company_name": "New Child Company Name"
  }'

Note: The response body from creating these “Registration Requests” will also provide you the “invite_link” which is the link that will be sent to the email provided. You can use this to share with other users whom you would like to complete the registration as well.

The response body will also contain the “id” of the Registration Request. You can use this to retrieve the Registration Request in order to obtain the status of the request from Middesk along with any Tax IDs if the request has been completed.

Retrieve Registration Request

Simply pass in the "id" of the Registration Request from the response of the create API call to retrieve a Registration Request and see the state of the requested "items". An "item" is a Tax Registration ID that has been requested for this state based on the tax_registration_types supplied.

Example:

curl https://api.middesk.com/v1/partner/registration_requests/123-reg-request-id \
  -u mk_live_2b7dc3728c80f8c278596ba9: \
  -H "Accept: application/json"

Example Responses:

Pending (shortly after submitted Registration Request - Employer has not completed request)

{
   "id": "123-reg-request-id",
   "state": "AK",
   "company_id": "123-middesk-company-id",
   "external_id": "555-external-company-id",
   "object": "registration_request",
   "created_at": "2023-04-01T15:30:55Z",
   "submitted_at": null,
   "status": "pending",
   "items": []
}

Submitted (Employer has completed and submitted registration. Awaiting on Government for IDs)

{
   "id": "123-reg-request-id",
   "state": "AK",
   "company_id": "123-middesk-company-id",
   "external_id": "555-external-company-id",
   "object": "registration_request",
   "created_at": "2023-04-01T15:30:55Z",
   "submitted_at": "2023-04-05T15:41:48Z",
   "status": "submitted",
   "items": [
      {
         "agency": "Department of Labor and Workforce Development",
         "label": "Employer Account Number",
         "value": null,
         "state": "AK",
         "updated_at": "2023-04-05T15:41:48Z"
      },
      {
         "agency": "Department of Labor and Workforce Development",
         "label": "Employer Unemployment Insurance (UI) Contribution Rate",
         "value": null,
         "state": "AK",
         "updated_at": "2023-04-05T15:41:48Z"
      }
   ]
}

Completed (All Registration items have been completed and IDs are available for you to export)

{
   "id": "123-reg-request-id",
   "state": "AK",
   "company_id": "123-middesk-company-id",
   "external_id": "555-external-company-id",
   "object": "registration_request",
   "created_at": "2023-04-01T15:30:55Z",
   "submitted_at": "2023-04-05T15:41:48Z",
   "status": "completed",
   "items": [
      {
         "agency": "Department of Labor and Workforce Development",
         "label": "Employer Account Number",
         "value": "12355599",
         "state": "AK",
         "updated_at": "2023-04-06T10:41:48Z"
      },
      {
         "agency": "Department of Labor and Workforce Development",
         "label": "Employer Unemployment Insurance (UI) Contribution Rate",
         "value": "5",
         "state": "AK",
         "updated_at": "2023-04-06T10:42:48Z"
      }
   ]
}

Webhooks

Instead of polling the "retrieve registration request" endpoint you can also set up Webhooks to be notified when Registration Requests are submitted by your employer and have item values updated for you to export.

You can configure the endpoint you want to receive webhooks to via the Partner Dashboard.

Go to your "Account" > "Settings" from the upper-right navigation.
Go to the "Webhooks" page from the left sidebar navigation under "DEVELOPERS".
Click on the "Add Webhook" button in the top right.

For the Cohosted API Integration we suggest you subscribe to the following "Enabled Events":

"registration_request.submitted"
"registration_request.updated"

registration_request.submitted

If subscribed, this event will be sent to your webhook endpoint whenever one of the requested state tax registrations has been submitted by the employer.

Example Payload:

{
  "account_id": "your-middesk-account-id",
  "created_at": "2023-02-08T18:04:43.939Z",
  "data" : {
    "object": {
      "object": "registration_request",
      "id": "middesk-registration-request-id",
      "state": "CA",
      "company_id": "middesk-child-company-id",
      "external_id": "external-child-company-id",
      "created_at": "2023-02-02T17:00:22Z",
      "submitted_at": "2023-02-08T18:04:43Z",
      "status": "submitted",
      "items": [
        {
          "agency": "Employment Development Department (EDD)",
          "label": "SUI Rate",
          "state": "CA",
          "updated_at": "2023-02-08T18:04:43Z",
          "value": null
        },
        {
           "agency": "Employment Development Department (EDD)",
           "label": "EDD number",
           "state": "CA",
           "updated_at": "2023-02-08T18:04:43Z",
           "value": null
        }
      ]
    }
  },
  "id": "middesk-event-id",
  "object": "event",
  "type": "registration_request.submitted"
}

registration_request.updated

If subscribed, this event will be sent to your webhook endpoint whenever one of the Tax Registration Items resulting from a submitted Registration Request has been marked as completed and the Tax ID is available for export.

Example Payload:

{
  "account_id": "your-middesk-account-id",
  "created_at": "2023-02-08T18:04:43.939Z",
  "data" : {
    "object": {
      "object": "registration_request",
      "id": "middesk-registration-request-id",
      "state": "CA",
      "company_id": "middesk-child-company-id",
      "external_id": "external-child-company-id",
      "created_at": "2023-02-02T17:00:22Z",
      "submitted_at": "2023-02-08T17:00:43Z",
      "status": "completed",
      "items": [
        {
          "agency": "Employment Development Department (EDD)",
          "label": "SUI Rate",
          "state": "CA",
          "updated_at": "2023-02-08T18:04:43Z",
          "value": "12"
        },
        {
           "agency": "Employment Development Department (EDD)",
           "label": "EDD number",
           "state": "CA",
           "updated_at": "2023-02-08T17:00:43Z",
           "value": "102030405"
        }
      ]
    }
  },
  "id": "middesk-event-id",
  "object": "event",
  "type": "registration_request.updated"
}