Partner integration endpoints

This reference documents two API endpoints used in Middesk’s Entity Management product for agent partners. These endpoints enable partners to create companies and applications on behalf of their customers through the agent API context.

Create a company

The Create a company endpoint creates a company record within a partner’s Middesk account.

A company represents one employer/entity with a single FEIN (Federal Employer Identification Number). Companies are the foundational entity for tax registrations, foreign qualifications, and other entity management services managed by the partner on behalf of their customers.

Account hierarchy

Partner companies exist within a simplified hierarchy:

Partner account: The partner’s top-level account
Employer account: Child accounts created under the partner, each containing one or many companies

When using this endpoint, the company is automatically associated with an employer account under the authenticated partner’s account.

Create companies with affiliate accounts

Partners can organize companies under different affiliate structures while maintaining centralized management. This approach is useful for partners who manage multiple brands, regional offices, or reseller relationships through affiliate accounts.

To create companies under an affiliate account, specify the affiliate’s partner_account_id as the partner_account_id parameter in the request. Authenticate with your partner-level API key (not the affiliate’s key).

The company is created under the affiliate’s account hierarchy, and all subsequent operations on the company are scoped to the affiliate account.

Request parameters

Required parameters

Parameter	Type	Description
`legal_name`	string	Legal name of the company
`ein`	string	Federal Employer Identification Number

Optional parameters

Parameter	Type	Description
`partner_account_id`	string	The partner account ID that will own this company (can be an affiliate account ID)
`id`	string	Custom ID for the company
`external_id`	string	Partner’s external reference ID for this company
`provider`	string	Integration provider name
`provider_access_token`	string	OAuth access token for provider integrations
`provider_refresh_token`	string	OAuth refresh token for provider integrations
`provider_company_id`	string	Company ID in the provider’s system
`dba_name`	string	Doing Business As name
`contact_email`	string	Primary contact email
`contact_name`	string	Primary contact name
`contact_phone_number`	string	Primary contact phone number
`contact_title`	string	Primary contact’s job title
`entity_type`	string	Legal entity type (corporation, llc, partnership, etc.)
`formation_date`	string	Date company was formed (YYYY-MM-DD format)
`formation_state`	string	State where company was formed (two-letter abbreviation)
`addresses`	array	Array of address objects (see address structure below)
`individuals`	array	Array of individual/owner objects
`businesses`	array	Array of related business entities

Address object structure

1 {
2   "address_line1": "string",
3   "address_line2": "string",
4   "city": "string",
5   "state": "string (two-letter abbreviation)",
6   "postal_code": "string",
7   "address_type": "primary | mailing | secondary"
8 }

Response structure

The response returns the created company object.

Field	Type	Description
`id`	string	Middesk’s unique identifier for the company
`partner_account_id`	string	Associated partner account ID (or affiliate account ID if created under affiliate)
`employer_account_id`	string	Associated employer account ID (auto-created)
`created_at`	timestamp	When the company was created
`updated_at`	timestamp	Last update timestamp

All submitted company details also return in the response.

When creating a partner company, the system also creates:

Employer account: Automatically created if one doesn’t exist for this customer
Company details: Extended company information
Addresses: Physical and mailing addresses
Individuals: Owners, officers, and authorized signatories
Businesses: Related business entities

Authentication

Creating companies with affiliate accounts requires partner API key authentication:

Production: Authorization: Bearer mk_live_{your_partner_key}
Sandbox: Authorization: Bearer mk_test_{your_partner_key}

When creating companies under affiliate accounts, always use the parent partner’s API key. The partner_account_id parameter determines which account owns the company, not the API key used for authentication.

Example request

$ curl -X POST https://api.middesk.com/v1/agent/partner/companies \
>   -H "Authorization: Bearer mk_live_50e41b..." \
>   -H "Content-Type: application/json" \
>   -d '{
>     "partner_account_id": "acc_partner123",
>     "legal_name": "Acme Corporation",
>     "ein": "12-3456789",
>     "external_id": "customer_12345",
>     "dba_name": "Acme Co",
>     "contact_email": "contact@acme.com",
>     "contact_name": "Jane Smith",
>     "contact_phone_number": "(555) 123-4567",
>     "entity_type": "corporation",
>     "formation_state": "DE",
>     "formation_date": "2020-01-15",
>     "addresses": [{
>       "address_line1": "123 Main St",
>       "city": "San Francisco",
>       "state": "CA",
>       "postal_code": "94105",
>       "address_type": "primary"
>     }]
>   }'

Example request for affiliate account

$ curl -X POST https://api.middesk.com/v1/agent/partner/companies \
>   -H "Authorization: Bearer mk_live_50e41b..." \
>   -H "Content-Type: application/json" \
>   -d '{
>     "partner_account_id": "acc_affiliate456",
>     "legal_name": "Regional Business LLC",
>     "ein": "98-7654321",
>     "external_id": "affiliate_customer_789",
>     "contact_email": "contact@regionalbiz.com",
>     "contact_name": "John Doe",
>     "entity_type": "llc",
>     "formation_state": "CA"
>   }'

Create an application

The Create an application endpoint creates an application for a partner company to register for tax registrations, foreign qualifications, or other entity management services.

Applications represent the employer’s intent to register with state/local agencies and collect the necessary information to complete those registrations. This endpoint is designed for partners managing the registration process on behalf of their customers.

Create an application with affiliate accounts

Partners can create applications for companies that belong to affiliate accounts. The application automatically inherits the account context from the company it references.

When creating applications for affiliate-owned companies, reference the company_id of a company created under the affiliate account and authenticate with your partner-level API key.

The application is associated with the affiliate’s partner_account_id. All application-related webhooks and updates include the affiliate account context.

This ensures proper attribution and reporting for affiliate-managed registrations.

Request parameters

Required parameters

Parameter	Type	Description
`company_id` or `company_external_id`	string	The partner company ID this application is for (can be a company owned by an affiliate account)

Optional parameters (prefill data)

When creating an application, prefill data to reduce employer friction:

Company details (legal_name, ein, entity_type)
Address information
Individual/owner information

Prefilling data streamlines the application process and improves completion rates.

Parameter	Type	Description
`redirect_uri`	string	URI to redirect to after application completion
`redirect_back_uri`	string	URI to redirect back to if the user exits the application

Response structure

The response returns the created application object.

Field	Type	Description
`id`	string	Unique application identifier
`company_id`	string	Associated partner company ID
`partner_account_id`	string	Associated partner account ID (reflects affiliate account if company is owned by affiliate)
`status`	string	Current status
`application_type`	string	Type of application
`invite_link`	string	Tokenized link for employer to complete application (if applicable)
`created_at`	timestamp	When the application was created
`submitted_at`	timestamp	When employer submitted (null if not submitted)

Example request

$ curl -X POST https://api.middesk.com/v1/agent/partner/applications \
>   -H "Authorization: Bearer mk_live_50e41b..." \
>   -H "Content-Type: application/json" \
>   -d '{
>     "company_id": "cmp_abc123",
>     "state": "NY",
>     "application_type": "new_registration",
>     "tax_registration_types": [
>       "state_unemployment_insurance",
>       "state_tax_withholdings"
>     ],
>     "jurisdictions": ["new_york_city_tax"],
>     "send_invite": true
>   }'

Example request for affiliate-owned company

$ curl -X POST https://api.middesk.com/v1/agent/partner/applications \
>   -H "Authorization: Bearer mk_live_50e41b..." \
>   -H "Content-Type: application/json" \
>   -d '{
>     "company_id": "cmp_affiliate789",
>     "state": "TX",
>     "application_type": "new_registration",
>     "tax_registration_types": [
>       "state_unemployment_insurance"
>     ],
>     "send_invite": false
>   }'

Webhooks for partner application updates

Partners should subscribe to these webhook events:

partner.application.created
partner.application.updated
partner.application.submitted

Webhook events for companies and applications under affiliate accounts include the affiliate’s partner_account_id in the payload, allowing partners to route notifications and updates appropriately.

Sandbox testing

Both partner endpoints are available in the sandbox environment:

Base URL: https://api-sandbox.middesk.com
API keys: Use test API keys: mk_test_{your_partner_key}

Use the sandbox to simulate registration outcomes using test endpoints, test different state requirements and workflows, and test affiliate account workflows by creating test affiliate accounts.

Error handling

Both endpoints return standard HTTP status codes:

Status Code	Description
`200`	Success
`400`	Bad request (validation errors)
`401`	Unauthorized (invalid API key)
`403`	Forbidden (insufficient partner permissions)
`404`	Not found (invalid company_id, etc.)
`500`	Server error

Error responses include:

1 {
2   "error": {
3     "type": "validation_error",
4     "message": "Description of the error",
5     "param": "parameter_name"
6   }
7 }

Get a demo

Contact your account manager or contact sales to inquire about access.

Create a company

Account hierarchy

Create companies with affiliate accounts

Request parameters

Required parameters

Optional parameters

Address object structure

Response structure

Related models

Authentication

Example request

Example request for affiliate account

Create an application

Create an application with affiliate accounts

Request parameters

Required parameters

Optional parameters (prefill data)

Response structure

Example request

Example request for affiliate-owned company

Webhooks for partner application updates

Sandbox testing

Error handling

Get a demo