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

Optional parameters

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.

All submitted company details also return in the response.

Related models

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}

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": "[email protected]",
>
    "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": "[email protected]",
>
    "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

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.

Response structure

The response returns the created application object.

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

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:

Error responses include:

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