---
title: "Create business (idempotent)"
method: POST
path: "/v1/platform/businesses/"
tags: ["Business Management"]
---

# Create business (idempotent)

`POST /v1/platform/businesses/`

## Request

- Base URL: `https://docs.thredfi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.thredfi.com/v1/platform/businesses/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP basic
  - HTTP bearer
  - HTTP bearer

Create a new business with idempotency support via external_id.

        **Supported Markets**: EU/UK, Nordic, and APAC countries (GB, DE, FR, NL, ES, BE, IT, IE, AT, PT, SE, NO, DK, FI, IS, MY, SG)

        **Entity Type Validation**:
        - **GB, DE, NL, ES, BE, MY, SG**: Must use country-specific entity types (see documentation)
        - **All other countries**: Any entity type string is accepted

        **Idempotency**: If a business with the same external_id already exists for your partner,
        this endpoint will return the existing business (HTTP 200) instead of creating a duplicate.

        **Response Metadata**: Includes `_meta` field indicating creation vs idempotent return.

        **Required Fields**: external_id, legal_name, entity_type, email

## Request body

- CreateBusinessRequest: Serializer for creating new businesses
  - `external_id` string, required: Your unique identifier for this business (used for idempotency)
  - `legal_name` string, required: Legal registered name of the business
  - `entity_type` string, required: Business entity type (e.g., 'limited', 'gmbh', 'bv'). Validated for GB, DE, NL, ES, BE. Any string accepted for other countries.
  - `phone_number` string: Business phone number
  - `tin` string: Tax identification number (other than VAT)
  - `vat_number` string: EU VAT registration number
  - `company_number` string: Company registration number (e.g., Companies House number for UK)
  - `country` string: ISO 3166-1 alpha-2 country code (e.g., GB, DE, NL, ES, MY, SG)
  - `province` string: Province or state within the country
  - `eu_nace_industry_code` string: European NACE industry classification code
  - `email` string, email, required: Primary email address for the business
  - `base_currency` string: Base currency for accounting (ISO 4217 code: EUR, GBP, USD, SEK, NOK, DKK, ISK, MYR, SGD)
  - `accounting_method` 'cash' | 'accrual': Accounting method: 'cash' or 'accrual' (default: accrual) * `cash` - Cash Basis * `accrual` - Accrual Basis
  - `fiscal_year_end` string, date: Fiscal year end date (format: YYYY-MM-DD, e.g., '2024-03-31' for March 31st year-end)
  - `metadata` unknown

## Response `201`

- Business: Full business serializer for list and detail views
  - `id` string, uuid, required: Unique identifier for the business
  - `external_id` string: Your unique identifier for this business
  - `legal_name` string, required: Legal registered name of the business
  - `name` string: Display name for the business (defaults to legal_name)
  - `entity_type` string: Business entity type (e.g., 'limited', 'gmbh', 'bv')
  - `phone_number` string: Business phone number
  - `tin` string: Tax identification number (other than VAT)
  - `vat_number` string: EU VAT registration number
  - `company_number` string: Company registration number (e.g., Companies House number for UK)
  - `country` string, required: ISO 3166-1 alpha-2 country code (e.g., GB, DE, NL, MY, SG)
  - `province` string: Province or state within the country
  - `eu_nace_industry_code` string: European NACE industry classification code
  - `email` string, email, required: Primary email address for the business
  - `base_currency` string, required: Base currency for accounting (ISO 4217 code)
  - `accounting_method` string, required: Accounting method: 'cash' or 'accrual'
  - `fiscal_year_end` string, date, required: Fiscal year end date
  - `activation_at` string, date-time, required: Date and time when the business was activated
  - `is_active` boolean, required: Whether the business is active (false if archived)
  - `created_at` string, date-time, required: Date and time when the business was created
  - `updated_at` string, date-time, required: Date and time when the business was last updated
  - `metadata` unknown

## Other responses

- `400`: Validation errors in request data
- `401`: Authentication required - missing or invalid API key
- `403`: Permission denied - insufficient privileges
- `404`: Resource not found
- `409`: Conflict - resource already exists or invalid state transition
- `422`: Unprocessable entity - business logic validation failed
- `500`: Internal server error

---

[API](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api.md) - [All operations](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/revisions/0c1918254db3?raw)