Manage business entities

Configure webhooks for entity management

Configure webhooks to receive notifications when registrations, information requests, item changes, and mail are created or updated.

Subscribe to events

You can subscribe to these event types: registration requests, jurisdiction registrations, information requests, item changes, and mail.

Registration request events

Recieve real-time updates about registration requests created via the POST /registration_requests endpoint.

  • registration_request.submitted sends when a state tax registration request is submitted by the employer.
  • registration_request.updated sends when a Tax Registration Item created by that submitted registration request is completed and its Tax IDs are available. Multiple updates are possible as items complete over time.

Use these example payloads to notify your systems of any changes to a registration request.

1{
2  "account_id": "your-middesk-account-id",
3  "created_at": "2023-02-08T18:04:43.939Z",
4  "data" : {
5    "object": {
6      "object": "registration_request",
7      "id": "middesk-registration-request-id",
8      "state": "CA",
9      "company_id": "middesk-child-company-id",
10      "created_at": "2023-02-02T17:00:22Z",
11      "submitted_at": "2023-02-08T18:04:43Z",
12      "status": "submitted",
13      "items": [
14        {
15          "agency": "Employment Development Department (EDD)",
16          "label": "SUI Rate",
17          "state": "CA",
18          "updated_at": "2023-02-08T18:04:43Z",
19          "value": null
20        },
21        {
22           "agency": "Employment Development Department (EDD)",
23           "label": "EDD number",
24           "state": "CA",
25           "updated_at": "2023-02-08T18:04:43Z",
26           "value": null
27        }
28      ]
29    }
30  },
31  "id": "middesk-event-id",
32  "object": "event",
33  "type": "registration_request.submitted"
34}

Understand the status of your jurisdiction registration requests.

StatusDescription
pendingregistration request has not yet been submitted by employer.
submittedregistration request has been submitted but not all Tax Registration Items are completed.
completedregistration request has been submitted and all Tax Registration Items are marked as completed.

Juridsiction registrations

  • agent_jurisdiction_registration.created sends when a jurisdiction registration is created by Middesk.
  • agent_jurisdiction_registration.updated sends whenever the status of a jurisdiction registration is updated by Middesk.

Use these example payloads to notify your systems of any changes to a jurisdiction registration.

1{
2   "id" => "5dcf54c3-7b81-43ad-94ac-70394fed291b",
3   "company_id" => "dbb0f373-b744-465e-941e-ab76d4194a86",
4   "external_id" => nil,
5   "status" => "middesk_processing",
6   "tax_type" => "FLI",
7   "jurisdiction_name" => "Connecticut Paid Leave",
8   "jurisdiction_slug" => "connecticut_paid_leave",
9   "created_at" => "2025-08-13T18:21:36Z",
10   "updated_at" => "2025-08-13T18:21:36Z",
11   "submitted_at" => nil,
12   "completed_at" => nil,
13   "status_updated_at" => "2025-08-13T18:21:36Z",
14   "blocked_by" => nil,
15   "blocked_until" => nil,
16   "transfer" => false,
17   "items" => [{
18      "agency" => "Connecticut Paid Family Leave Authority",
19      "label" => "CT PFML Account Number",
20      "key" => "ct_fli_account_number",
21      "value" => nil,
22      "state" => "CT",
23      "status" => "open",
24      "updated_at" => "2025-08-13T18:21:36Z"
25   }],
26   "registration_request_id" => "e5085880-fd34-4a8d-a91c-30b6d44ac6e5",
27   "object" => "jurisdiction_registration"
28}

Understand the status of your jurisdiction registration requests.

StatusDescription
information_requestedJurisdiction registration requires additional information from the customer before processing can continue.
blocked_by_governmentJurisdiction registration is blocked by government requirements (for example, waiting for hire date, payroll date, or liability date).
middesk_processingJurisdiction registration is being processed by Middesk staff.
government_processingJurisdiction registration has been submitted to the government and is being processed by the government.
completedJurisdiction registration has been completed and deliverables (like Account Number, UI Account number, and UI Tax rates) are available.
duplicateJurisdiction registration and corresponding deliverables were marked as duplicate since the company’s information was already registered with the state or local government.
unmanagedJurisdiction registration is not managed by Middesk.
not_requiredJurisdiction registration is deemed by the government as not required for this business in this jurisdiction.

Information request events

  • agent_info_request.created sends when an information request is created. The link to the web form for the information request is provided in the url property.
  • agent_info_request.updated sends when an information request is updated.
  • agent_info_request.voided sends when an information request is voided. A voided information request no longer needs action.

Use these example payloads to notify your systems of any changes to an information request.

1{
2  "account_id": "your-middesk-account-id",
3  "created_at": "2024-11-27T18:04:43.939Z",
4  "id": "middesk-event-id",
5  "object": "event",
6  "type": "agent_info_request.created",
7  "data" :
8    {
9    "object": "agent_exception",
10    "id": "12de5aa8-ff34-4aae-9b7a-dd776d200eba",
11    "created_at": "2024-12-19T15:52:49.324Z",
12    "updated_at": "2024-12-19T15:52:49.324Z",
13    "completed_at": null,
14    "voided_at": null,
15    "url": "https://agent.middesk.com/info_requests/12de5aa8-ff34-4aae-9b7a-dd776d200eba",
16    "owner": {
17      "id": "5c94b5d0-d103-403e-befc-879bee38fc4b",
18      "state": "CA",
19      "owner_type": "Agent::TaxRegistration",
20      "application_type": "new_registration",
21      "registration": true,
22      "legal_name": "Middesk",
23      "company_id": "259fc2fa-ae6d-4b73-9610-ba500e274078",
24      "provider_company_id": null,
25      "external_id": "808b33dd-3755-42c1-aeb6-5710b5c91d47"
26    },
27    "company": {
28      "id": "259fc2fa-ae6d-4b73-9610-ba500e274078",
29      "legal_name": "Middesk",
30      "provider_company_id": null,
31      "external_id": "808b33dd-3755-42c1-aeb6-5710b5c91d47"
32    },
33    "account": {
34      "id": "a8caeb8d-67a7-4d9b-93e3-72b25dfa136e",
35      "name": "Heaney, Kertzmann and Johns",
36      "slug": "dolor-in",
37      "parent_account": null
38    }
39  }
40}

Item change events

  • agent_item_change.created sends when an item change is created.
  • agent_item_change.updated sends when an item change is updated. This includes when it is applied to the existing tax registration item.

Use these example payloads to notify your systems of any changes to an item.

1{
2  "account_id": "your-middesk-account-id",
3  "created_at": "2024-12-19T19:10:11.859Z",
4  "id": "middesk-event-id",
5  "object": "event",
6  "type": "agent_item_change.created",
7  "data" :
8    {
9      "object": "agent_item_change",
10      "id": "481e5c1b-228a-4427-92d9-3835973caaac",
11      "created_at": "2024-12-19T19:10:11.859Z",
12      "effective_at": "2025-01-19",
13      "applied_at": null,
14      "from_value": "3.4%",
15      "to_value": "3.6%",
16      "tax_registration_item": {
17        "id": "64e01f8a-f1d8-4cb9-9f54-7feef4eb979f",
18        "agency": "Employment Development Department (EDD)",
19        "key": "ca_sui_rate",
20        "label": "SUI Rate",
21        "requirement_type": "state_unemployment_insurance",
22        "status": "active",
23        "value": "3.4%",
24        "state": "CA"
25      },
26      "tax_registration": {
27        "id": "88e7f433-3a1b-4a26-846f-bdf1e3d2a4bc",
28        "state": "CA",
29        "tax_types": [
30          "state_unemployment_insurance",
31          "state_tax_withholdings"
32        ],
33        "status": "active"
34      },
35      "company": {
36        "legal_name": "Middesk, Inc.",
37        "dba_name": "Middesk",
38        "provider_company_id": null,
39        "external_id": "9bdbbac4-1b83-4f92-9272-60a82b41b0da",
40        "id": "0e7c8bd5-8a9e-481b-af69-fe6f99c69df5"
41      },
42      "account": {
43        "id": "0dd06e4d-57bc-4977-b596-f8a277f42b75",
44        "name": "Mertz, Fay and Schoen",
45        "slug": "repellat_aut",
46        "parent_account": null
47      }
48    }
49}

Mail

  • agent_mail.available sends when a piece of mail is newly available in our system.

Use this example payload to notify your systems of mail recieved by Middesk.

agenet_mail.available
1{
2  "account_id": "your-middesk-account-id",
3  "created_at": "2024-11-27T18:04:43.939Z",
4  "id": "middesk-event-id",
5  "object": "event",
6  "type": "agent_mail.available",
7  "data" :
8  {
9    "object": "agent_mail",
10    "id": "1df541f1-fee9-4612-be6b-c9dd11b557b9",
11    "sender_name": "Department of Revenue",
12    "recipient_name": "Your company name",
13    "agency_name": "Department of Revenue",
14    "tag_names": ["no_action_required"],
15    "state": "CA",
16    "owner": {
17      "type": "tax_registration",
18      "id": "d7376440-a647-4d62-bf8b-111eb924f355"
19    },
20    "source": {
21      "type": "tax_registration",
22      "id": "d7376440-a647-4d62-bf8b-111eb924f355"
23    },
24    "company": {
25      "legal_name": "Middesk",
26      "dba_name": "Deskmid",
27      "provider_company_id": null,
28      "external_id": "b4901bfe-4777-4c6a-86e8-a6b43c6df904"
29    },
30    "account": {
31      "id": "13a25067-a804-4f1c-a9f6-d131f652df40",
32      "name": "O'Reilly-Robel",
33      "slug": "possimus_maxime",
34      "parent_account": {
35        "id": "a7be256c-25e6-474c-ac58-7f9dc32bc0ff",
36        "name": "Stoltenberg, Klocko and Rosenbaum",
37        "slug": "voluptate-et"
38      }
39    },
40    "document_url": "https://storage.googleapis.com/middesk/abc123",
41  }
42}
Get a demo
Contact your account manager or contact sales to inquire about access.