For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Contact SalesGet Support
HomeGuidesAPI reference
HomeGuidesAPI reference
  • Get started
    • Quickstart—Verify a Business
    • Quickstart—Register an entity for payroll taxes
    • Learn how Middesk works
    • Security
    • Changelog
  • Build with Middesk
    • Get your API keys
    • Understand API changes
    • Status codes and errors reference
    • Implement webhooks
    • Secure webhooks
    • Use GraphQL
    • Connect MCP
  • Verify a business (KYB)
    • Verify TIN
    • Verify name and address
    • Verify Secretary of State status
    • Verify owners and officers
    • Screen for sanctions and watchlists
    • Search for adverse media
    • Search for Politically Exposed Persons
    • Implement KYC
    • Discover connections
    • Evaluate online presence
    • Assess credit risk
    • Accelerate onboarding
    • Monitor business activity
    • Manage business entities
      • Learn the registration lifecycle
      • Register an entity for payroll taxes
      • Configure webhooks for entity management
    • Work with agents
LogoLogo
Contact SalesGet Support
On this page
  • Subscribe to events
  • Registration request events
  • Jurisdiction registrations
  • Information request events
  • Item change events
  • Mail
Manage business entities

Configure webhooks for entity management

Was this page helpful?
Previous

Invite employers

Next
Built with

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

Receive 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.

Jurisdiction 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": null,
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": null,
12  "completed_at": null,
13  "status_updated_at": "2025-08-13T18:21:36Z",
14  "blocked_by": null,
15  "blocked_until": null,
16  "transfer": false,
17  "items": [
18    {
19      "agency": "Connecticut Paid Family Leave Authority",
20      "label": "CT PFML Account Number",
21      "key": "ct_fli_account_number",
22      "value": null,
23      "state": "CT",
24      "status": "open",
25      "updated_at": "2025-08-13T18:21:36Z"
26    }
27  ],
28  "registration_request_id": "e5085880-fd34-4a8d-a91c-30b6d44ac6e5",
29  "object": "jurisdiction_registration"
30}

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 Middesk.

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

agent_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.