> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Partner integration endpoints

> Use Middesk partner entity management endpoints to create companies and applications on behalf of your customers.

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](/api-reference/entity-management/companies/create-a-company) 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 owns 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, or partnership)                           |
| `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

```json
{
  "address_line1": "string",
  "address_line2": "string",
  "city": "string",
  "state": "string (two-letter abbreviation)",
  "postal_code": "string",
  "address_type": "primary | mailing | secondary"
}
```

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

### 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}`

> **Note**
>
> 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

```bash
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

```bash
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](/api-reference/entity-management/applications/create-an-application) 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

```bash
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

```bash
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`

> **Note**
>
> 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`)             |
| `500`       | Server error                                 |

Error responses include:

```json
{
  "error": {
    "type": "validation_error",
    "message": "Description of the error",
    "param": "parameter_name"
  }
}
```

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.