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

# Create a sub-account

POST https://api.middesk.com/v1/sub_accounts
Content-Type: application/json

Creates a sub-account and provisions an initial sandbox API key. external_id is an idempotency key unique within the parent account: repeating a request with the same external_id returns the existing sub-account with 200 and no api_keys field. With inherit_products_from_parent enabled (the default), parent product changes cascade to the sub-account. When disabled, products is required and the sub-account is independent.

Reference: https://docs.middesk.com/api-reference/sub-accounts/create-sub-account

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an object.

- `name` (string, required) — Display name for the sub-account
- `external_id` (string, required) — Idempotency key unique within the parent account. Reusing it returns the existing sub-account instead of creating another one.
- `products` (list of enum, optional) — Products enabled for the sub-account. Every value must be enabled on the parent account. Required when inherit_products_from_parent is false.
  - Allowed values: `identity`, `liens`, `adverse_media`, `bankruptcies`, `business_enrichment`, `documents`, `enhanced_screenings`, `kyc_doc_v`, `kyc`, `litigations`, `people_litigations`, `people_bankruptcies`, `people_tax_liens`, `people_ucc_liens`, `people_criminal_history`, `tin`, `website`, `business_verification_qualify`, `business_verification_verify`, `tax_liens`, `ucc_liens`, `merchant_risk`, `risk`, `email_risk`, `phone_risk`, `international_business_verification`
- `inherit_products_from_parent` (boolean, optional, default: true) — When true, product changes on the parent cascade to this sub-account. When false, the sub-account's products are independent and products is required.
- `website` (string, optional) — Required for accounts with a Middesk partner profile
- `vertical` (enum, optional) — Required for accounts with a Middesk partner profile
  - Allowed values: `fintech_non_bank_financial_services`, `banks`, `manufacturing_industrial`, `technology_companies`, `freight_logistics`, `other`, `government`
- `sub_vertical` (enum, optional) — Required for accounts with a Middesk partner profile. The value must belong to the selected vertical.
  - Allowed values: `digital_banking_neobanks`, `insurance`, `lending_non_bank_digital`, `lending_non_bank_traditional`, `payments_acquiring_issuing`, `payroll_benefits_management`, `other_fintech_non_bank_financial_services`, `community_banks`, `credit_unions`, `national_banks`, `regional_banks`, `automotive`, `construction`, `healthcare_medical`, `other_manufacturing_industrial`, `b2b_software_vertical_saas`, `data_services`, `ecommerce`, `hardware`, `marketplaces`, `telecomm`, `other_technology_companies`, `freight_logistics`, `government`, `other`
- `use_case` (enum, optional) — Required for accounts with a Middesk partner profile
  - Allowed values: `banking`, `lending`, `payments`, `business_marketplace`, `agent`, `tax_registrations`, `less_regulated_kyb`, `account_opening`, `term_loans`, `working_capital_loans`, `equipment_finance`, `line_of_credit`, `invoice_factoring`, `merchant_cash_advance`, `trade_credit`, `expense_management`, `payroll_tax_account`, `compliance_for_bank_account_opening`, `compliance_for_commercial_mortgages`, `compliance_for_issuing_an_insurance_policy`, `compliance_for_loan_origination`, `compliance_for_payments_merchant_onboarding`, `compliance_for_treasury_management`, `compliance_other`, `credit_decisioning_for_loan_origination`, `filing_a_lien_for_loan_origination`, `filing_a_lien_other`, `fraud_prevention_for_bank_account_opening`, `fraud_prevention_for_issuing_an_insurance_policy`, `fraud_prevention_for_loan_origination`, `fraud_prevention_for_payments_merchant_onboarding`, `fraud_prevention_for_un_regulated_business_onboarding`, `fraud_prevention_other`, `tax_compliance_requirements_for_processing_payroll`, `underwriting_for_issuing_an_insurance_policy`, `other`
- `contact` (SubAccountCreateParamContact, optional) — Required for accounts with a Middesk partner profile
- `deal_name` (string, optional)
- `estimated_volume` (integer, optional)
- `go_live_date` (date, optional) — Future date in YYYY-MM-DD format

## Response

### 200

existing sub-account returned for the external ID

- `object` (enum, required)
  - Allowed values: `sub_account`
- `id` (string, required)
- `name` (string, required)
- `external_id` (string, required, nullable) — Idempotency key supplied by the parent account, unique within that parent
- `enabled` (boolean, required)
- `products` (list of string, required)
- `created_at` (datetime, required)

## Errors

### 400 Create Sub Account Request Bad Request Error

invalid request

- `errors` (list of ErrorResponseErrorsItem, required)

### 403 Create Sub Account Request Forbidden Error

sub-account provisioning not enabled

- `errors` (list of ErrorResponseErrorsItem, required)

## Types

### SubAccountCreateParamContact

Required for accounts with a Middesk partner profile

- `first_name` (string, required)
- `last_name` (string, required)
- `email` (string, required)
- `middle_name` (string, optional)

### ErrorResponseErrorsItem

- `message` (string, required)
- `parameter` (string, optional) — Request parameter associated with the error, when applicable

## Examples

### Create a sub-account that inherits products

**Request**

```json
{
  "name": "Acme Corp",
  "external_id": "ext-123"
}
```

**Response**

```json
{
  "object": "sub_account",
  "id": "8c0d8bd1-9ea8-4ae7-bf3e-7f6bd94a1de7",
  "name": "Acme Corp",
  "external_id": "ext-123",
  "enabled": true,
  "products": [
    "identity"
  ],
  "created_at": "2026-08-17T19:00:00Z"
}
```

**SDK Code**

```python Create a sub-account that inherits products
import requests

url = "https://api.middesk.com/v1/sub_accounts"

payload = {
    "name": "Acme Corp",
    "external_id": "ext-123"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Create a sub-account that inherits products
const url = 'https://api.middesk.com/v1/sub_accounts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Acme Corp","external_id":"ext-123"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Create a sub-account that inherits products
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.middesk.com/v1/sub_accounts"

	payload := strings.NewReader("{\n  \"name\": \"Acme Corp\",\n  \"external_id\": \"ext-123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Create a sub-account that inherits products
require 'uri'
require 'net/http'

url = URI("https://api.middesk.com/v1/sub_accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Acme Corp\",\n  \"external_id\": \"ext-123\"\n}"

response = http.request(request)
puts response.read_body
```

```java Create a sub-account that inherits products
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.middesk.com/v1/sub_accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Acme Corp\",\n  \"external_id\": \"ext-123\"\n}")
  .asString();
```

```php Create a sub-account that inherits products
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.middesk.com/v1/sub_accounts', [
  'body' => '{
  "name": "Acme Corp",
  "external_id": "ext-123"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Create a sub-account that inherits products
using RestSharp;

var client = new RestClient("https://api.middesk.com/v1/sub_accounts");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Acme Corp\",\n  \"external_id\": \"ext-123\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Create a sub-account that inherits products
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Acme Corp",
  "external_id": "ext-123"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.middesk.com/v1/sub_accounts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Create a sub-account with partner metadata

**Request**

```json
{
  "name": "Acme Corp",
  "external_id": "ext-123",
  "website": "https://example.com",
  "vertical": "banks",
  "sub_vertical": "community_banks",
  "use_case": "banking",
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "middle_name": "Q"
  },
  "deal_name": "Acme rollout",
  "estimated_volume": 5000,
  "go_live_date": "2027-01-15"
}
```

**Response**

```json
{
  "object": "sub_account",
  "id": "8c0d8bd1-9ea8-4ae7-bf3e-7f6bd94a1de7",
  "name": "Acme Corp",
  "external_id": "ext-123",
  "enabled": true,
  "products": [
    "identity"
  ],
  "created_at": "2026-08-17T19:00:00Z"
}
```

**SDK Code**

```python Create a sub-account with partner metadata
import requests

url = "https://api.middesk.com/v1/sub_accounts"

payload = {
    "name": "Acme Corp",
    "external_id": "ext-123",
    "website": "https://example.com",
    "vertical": "banks",
    "sub_vertical": "community_banks",
    "use_case": "banking",
    "contact": {
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "middle_name": "Q"
    },
    "deal_name": "Acme rollout",
    "estimated_volume": 5000,
    "go_live_date": "2027-01-15"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Create a sub-account with partner metadata
const url = 'https://api.middesk.com/v1/sub_accounts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Acme Corp","external_id":"ext-123","website":"https://example.com","vertical":"banks","sub_vertical":"community_banks","use_case":"banking","contact":{"first_name":"Jane","last_name":"Doe","email":"jane@example.com","middle_name":"Q"},"deal_name":"Acme rollout","estimated_volume":5000,"go_live_date":"2027-01-15"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Create a sub-account with partner metadata
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.middesk.com/v1/sub_accounts"

	payload := strings.NewReader("{\n  \"name\": \"Acme Corp\",\n  \"external_id\": \"ext-123\",\n  \"website\": \"https://example.com\",\n  \"vertical\": \"banks\",\n  \"sub_vertical\": \"community_banks\",\n  \"use_case\": \"banking\",\n  \"contact\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"email\": \"jane@example.com\",\n    \"middle_name\": \"Q\"\n  },\n  \"deal_name\": \"Acme rollout\",\n  \"estimated_volume\": 5000,\n  \"go_live_date\": \"2027-01-15\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Create a sub-account with partner metadata
require 'uri'
require 'net/http'

url = URI("https://api.middesk.com/v1/sub_accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Acme Corp\",\n  \"external_id\": \"ext-123\",\n  \"website\": \"https://example.com\",\n  \"vertical\": \"banks\",\n  \"sub_vertical\": \"community_banks\",\n  \"use_case\": \"banking\",\n  \"contact\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"email\": \"jane@example.com\",\n    \"middle_name\": \"Q\"\n  },\n  \"deal_name\": \"Acme rollout\",\n  \"estimated_volume\": 5000,\n  \"go_live_date\": \"2027-01-15\"\n}"

response = http.request(request)
puts response.read_body
```

```java Create a sub-account with partner metadata
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.middesk.com/v1/sub_accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Acme Corp\",\n  \"external_id\": \"ext-123\",\n  \"website\": \"https://example.com\",\n  \"vertical\": \"banks\",\n  \"sub_vertical\": \"community_banks\",\n  \"use_case\": \"banking\",\n  \"contact\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"email\": \"jane@example.com\",\n    \"middle_name\": \"Q\"\n  },\n  \"deal_name\": \"Acme rollout\",\n  \"estimated_volume\": 5000,\n  \"go_live_date\": \"2027-01-15\"\n}")
  .asString();
```

```php Create a sub-account with partner metadata
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.middesk.com/v1/sub_accounts', [
  'body' => '{
  "name": "Acme Corp",
  "external_id": "ext-123",
  "website": "https://example.com",
  "vertical": "banks",
  "sub_vertical": "community_banks",
  "use_case": "banking",
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "middle_name": "Q"
  },
  "deal_name": "Acme rollout",
  "estimated_volume": 5000,
  "go_live_date": "2027-01-15"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Create a sub-account with partner metadata
using RestSharp;

var client = new RestClient("https://api.middesk.com/v1/sub_accounts");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Acme Corp\",\n  \"external_id\": \"ext-123\",\n  \"website\": \"https://example.com\",\n  \"vertical\": \"banks\",\n  \"sub_vertical\": \"community_banks\",\n  \"use_case\": \"banking\",\n  \"contact\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"email\": \"jane@example.com\",\n    \"middle_name\": \"Q\"\n  },\n  \"deal_name\": \"Acme rollout\",\n  \"estimated_volume\": 5000,\n  \"go_live_date\": \"2027-01-15\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Create a sub-account with partner metadata
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Acme Corp",
  "external_id": "ext-123",
  "website": "https://example.com",
  "vertical": "banks",
  "sub_vertical": "community_banks",
  "use_case": "banking",
  "contact": [
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "middle_name": "Q"
  ],
  "deal_name": "Acme rollout",
  "estimated_volume": 5000,
  "go_live_date": "2027-01-15"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.middesk.com/v1/sub_accounts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```