---
title: "Create a customer"
method: POST
path: "/v1/platform/businesses/{business_id}/customers/"
tags: ["Customers"]
---

# Create a customer

`POST /v1/platform/businesses/{business_id}/customers/`

## 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/{business_id}/customers/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP basic
  - HTTP bearer
  - HTTP bearer

Create a new customer within a business. Returns the created customer in the same format as the get customer endpoint.

## Path parameters

- `business_id` string, uuid, required

## Request body

- CreateCustomerRequest: Serializer for creating new customers
  - `external_id` string: Your unique identifier for this customer (used for idempotency)
  - `reference_number` string: Customer reference number for invoices and statements
  - `individual_name` string: Individual/contact person name (required if company_name not provided)
  - `company_name` string: Registered company name (required if individual_name not provided)
  - `email` string, email: Primary email address for the customer
  - `mobile_phone` string: Mobile phone number
  - `office_phone` string: Office/landline phone number
  - `address_line1` string: Street address line 1
  - `address_line2` string: Street address line 2 (building, suite, etc.)
  - `city` string: City or town
  - `state_county` string: State, county, or region
  - `postal_code` string: Postal/ZIP code
  - `country` string: ISO 3166-1 alpha-2 country code
  - `vat_number` string: VAT registration number (for UK: GB followed by 9 digits)
  - `tax_exempt` boolean: Whether customer is exempt from tax/VAT
  - `status` 'active' | 'archived' | 'suspended': * `active` - Active * `archived` - Archived * `suspended` - Suspended
  - `transaction_tags` unknown[]: Array of tags for categorization and filtering
    - unknown
  - `notes` string: Internal notes about the customer
  - `metadata` unknown
  - `payment_terms_days` integer: Number of days for payment terms (e.g., 30 for Net 30)
  - `credit_limit_cents` integer: Maximum credit limit in cents (e.g., 100000 for £1,000)
  - `document` CustomerDocumentUploadRequest: Customer specific document upload payload.
    - `file` string, binary
    - `document_type` string
    - `upload_source` string
    - `metadata` unknown
    - `tags` unknown

## Response `201`

- Customer: Main customer serializer for customer API endpoints Returns customer information with comprehensive details Used for both list and detail responses
  - `type` string, required: Type identifier (always 'CustomerData')
  - `id` string, uuid, required: Unique identifier for the customer
  - `external_id` string, required: Your unique identifier for this customer (used for idempotency)
  - `reference_number` string, required: Customer reference number for invoices and statements
  - `individual_name` string, required: Individual/contact person name (required if company_name not provided)
  - `company_name` string, required: Registered company name (required if individual_name not provided)
  - `display_name` string, required: Display name for the customer (auto-generated from company_name or individual_name)
  - `email` string, email, required: Primary email address for the customer
  - `mobile_phone` string, required: Mobile phone number
  - `office_phone` string, required: Office/landline phone number
  - `address_line1` string, required: Street address line 1
  - `address_line2` string, required: Street address line 2 (building, suite, etc.)
  - `city` string, required: City or town
  - `state_county` string, required: State, county, or region
  - `postal_code` string, required: Postal/ZIP code
  - `country` string, required: ISO 3166-1 alpha-2 country code
  - `full_address` string, required: Complete formatted address with all fields
  - `address_string` string, required: Single-line formatted address
  - `vat_number` string, required: VAT registration number (for UK: GB followed by 9 digits)
  - `tax_exempt` boolean, required: Whether customer is exempt from tax/VAT
  - `status` string, required: Customer status (ACTIVE or ARCHIVED)
  - `is_active` boolean, required: Whether the customer is active (read-only)
  - `is_archived` boolean, required: Whether the customer is archived (read-only)
  - `transaction_tags` unknown[], required: Array of tags for categorization and filtering
    - unknown
  - `notes` string, required: Internal notes about the customer
  - `metadata` unknown, required
  - `payment_terms_days` integer, required: Number of days for payment terms (e.g., 30 for Net 30)
  - `credit_limit` integer, required: Maximum credit limit in cents (e.g., 100000 for £1,000)
  - `credit_limit_cents` integer, required: Maximum credit limit in cents (e.g., 100000 for £1,000)
  - `outstanding_balance` integer, required: Current outstanding balance in cents (read-only, computed)
  - `documents` DocumentFileUrl[], required: All documents linked to this customer with presigned URLs (retrieve only, not in list)
    - `url` string, uri, required: Presigned URL for document download
    - `expires_in` integer, required: Seconds until URL expires
    - `document_id` string, uuid, required: Document UUID
    - `file_name` string, required: Original document filename
    - `file_size` integer, required: File size in bytes
    - `mime_type` string, required: MIME type of the document
  - `created_at` string, date-time, required: Date and time when the customer was created
  - `updated_at` string, date-time, required: Date and time when the customer was last updated
  - `archived_at` string, date-time, required: Date and time when the customer was archived (null if active)

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