> ## Documentation Index > Fetch the complete documentation index at: https://docs.thredfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create business (idempotent) > 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 ## OpenAPI ````yaml POST /v1/platform/businesses/ openapi: 3.0.3 info: title: Thredfi Accounting Platform API version: 1.0.0 description: >- Comprehensive API for accounting, invoice management, open banking, and intelligence services. servers: [] security: [] paths: /v1/platform/businesses/: post: tags: - Business Management summary: Create business (idempotent) description: |2- 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 operationId: create_business requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBusinessRequest' examples: UKLimitedCompany: value: external_id: customer-123 legal_name: Acme Coffee Limited entity_type: limited email: accounting@acmecoffee.co.uk country: GB base_currency: GBP phone_number: +44 20 1234 5678 vat_number: GB123456789 company_number: '12345678' province: Greater London accounting_method: accrual fiscal_year_end: '2024-03-31' metadata: erp_id: ERP-12345 industry: hospitality summary: UK Limited Company GermanGmbH: value: external_id: de-company-456 legal_name: Mustermann Consulting GmbH entity_type: gmbh email: info@mustermann.de country: DE base_currency: EUR vat_number: DE123456789 tin: 12/345/67890 accounting_method: accrual summary: German GmbH application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateBusinessRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateBusinessRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/Business' examples: UKLimitedCompany: value: id: 3c90c3cc-0d44-4b50-8888-8dd25736052a external_id: customer-123 legal_name: Acme Coffee Limited name: Acme Coffee Ltd entity_type: limited phone_number: +44 20 1234 5678 tin: '1234567890' vat_number: GB123456789 company_number: '12345678' country: GB province: Greater London eu_nace_industry_code: '56.30' email: accounting@acmecoffee.co.uk base_currency: GBP accounting_method: accrual fiscal_year_end: '2024-03-31' activation_at: '2024-01-15T10:30:00Z' is_active: true created_at: '2024-01-15T10:30:00Z' updated_at: '2024-03-20T14:22:00Z' metadata: erp_id: ERP-12345 industry: hospitality summary: UK Limited Company description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' description: Validation errors in request data '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication required - missing or invalid API key '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission denied - insufficient privileges '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Resource not found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict - resource already exists or invalid state transition '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable entity - business logic validation failed '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error security: - PartnerJWT: [] - BusinessScopedJWT: [] - BasicAuth: [] - BearerUnscoped: [] - BearerBusinessScoped: [] components: schemas: CreateBusinessRequest: type: object description: Serializer for creating new businesses properties: external_id: type: string minLength: 1 description: Your unique identifier for this business (used for idempotency) maxLength: 255 legal_name: type: string minLength: 1 description: Legal registered name of the business maxLength: 255 entity_type: type: string minLength: 1 description: >- Business entity type (e.g., 'limited', 'gmbh', 'bv'). Validated for GB, DE, NL, ES, BE. Any string accepted for other countries. phone_number: type: string description: Business phone number tin: type: string description: Tax identification number (other than VAT) vat_number: type: string description: EU VAT registration number maxLength: 20 company_number: type: string description: Company registration number (e.g., Companies House number for UK) maxLength: 20 country: type: string minLength: 1 default: GB description: ISO 3166-1 alpha-2 country code (e.g., GB, DE, NL, ES, MY, SG) maxLength: 2 province: type: string description: Province or state within the country maxLength: 100 eu_nace_industry_code: type: string description: European NACE industry classification code maxLength: 10 email: type: string format: email minLength: 1 description: Primary email address for the business base_currency: type: string minLength: 1 default: GBP description: >- Base currency for accounting (ISO 4217 code: EUR, GBP, USD, SEK, NOK, DKK, ISK, MYR, SGD) maxLength: 3 accounting_method: enum: - cash - accrual type: string x-spec-enum-id: 6f6d0e718e73bb81 default: accrual description: |- Accounting method: 'cash' or 'accrual' (default: accrual) * `cash` - Cash Basis * `accrual` - Accrual Basis fiscal_year_end: type: string format: date description: >- Fiscal year end date (format: YYYY-MM-DD, e.g., '2024-03-31' for March 31st year-end) metadata: description: Custom JSON metadata for partner-specific data required: - email - entity_type - external_id - legal_name Business: type: object description: Full business serializer for list and detail views properties: id: type: string format: uuid readOnly: true description: Unique identifier for the business external_id: type: string description: Your unique identifier for this business legal_name: type: string description: Legal registered name of the business maxLength: 255 name: type: string description: Display name for the business (defaults to legal_name) maxLength: 255 entity_type: type: string description: Business entity type (e.g., 'limited', 'gmbh', 'bv') phone_number: type: string description: Business phone number tin: type: string description: Tax identification number (other than VAT) vat_number: type: string description: EU VAT registration number company_number: type: string description: Company registration number (e.g., Companies House number for UK) country: type: string description: ISO 3166-1 alpha-2 country code (e.g., GB, DE, NL, MY, SG) maxLength: 2 province: type: string description: Province or state within the country maxLength: 100 eu_nace_industry_code: type: string description: European NACE industry classification code maxLength: 10 email: type: string format: email description: Primary email address for the business base_currency: type: string description: Base currency for accounting (ISO 4217 code) maxLength: 3 accounting_method: type: string description: 'Accounting method: ''cash'' or ''accrual''' maxLength: 20 fiscal_year_end: type: string format: date description: Fiscal year end date activation_at: type: string format: date-time readOnly: true description: Date and time when the business was activated is_active: type: boolean readOnly: true description: Whether the business is active (false if archived) created_at: type: string format: date-time readOnly: true description: Date and time when the business was created updated_at: type: string format: date-time readOnly: true description: Date and time when the business was last updated metadata: description: Custom JSON metadata for partner-specific data required: - accounting_method - activation_at - base_currency - country - created_at - email - fiscal_year_end - id - is_active - legal_name - updated_at ValidationErrorResponse: type: object description: Validation error response with field-specific errors properties: error_code: type: string description: Error code (e.g., 'validation_error') message: type: string nullable: true description: Human-readable error message detail: type: object additionalProperties: {} description: Contains field_errors and additional context request_id: type: string description: Request ID for tracing required: - detail - error_code - message ErrorResponse: type: object description: Standard error response format properties: error_code: type: string description: Error code for programmatic handling message: type: string nullable: true description: Human-readable error message detail: type: object additionalProperties: {} description: Additional error details including field_errors and debug info request_id: type: string description: Request ID for tracing required: - error_code - message securitySchemes: PartnerJWT: type: http scheme: bearer bearerFormat: JWT description: >- Partner-level JWT token (unscoped). Token payload includes `partner_id`. Business access is validated via partner ownership. Format: `Bearer ` **Use this for**: Multi-business operations where the business_id is specified in the URL and partner has access to multiple businesses. BusinessScopedJWT: type: http scheme: bearer bearerFormat: JWT description: >- Business-scoped JWT token. Token payload includes `business_id` to automatically scope requests. Format: `Bearer ` **Use this for**: Business-specific operations where the business context is embedded in the token. BasicAuth: type: http scheme: basic description: >- Basic authentication for OAuth2 token endpoint. Use partner_uuid:api_key as username:password. Example: Authorization: Basic base64(partner_uuid:api_key) BearerUnscoped: type: http scheme: bearer bearerFormat: JWT description: >- Partner (unscoped) JWT Bearer token. Obtain via POST /v1/platform/oauth2/token with Basic auth (partner_uuid:api_key). Use header: Authorization: Bearer {access_token} BearerBusinessScoped: type: http scheme: bearer bearerFormat: JWT description: >- Business-scoped JWT Bearer token. Obtain via POST /v1/platform/{business_id}/oauth2/token/ using a partner Bearer token. Only valid for endpoints whose URL contains that business_id. ````