### Create Business (OpenAPI)

Source: https://docs.thredfi.com/api-reference/business-management/create-business

Defines the POST /v1/platform/businesses/ endpoint for creating a new business. Supports idempotency via external_id and specifies required fields and supported markets. Includes example request bodies for UK and German businesses and example responses.

```yaml
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: |
                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, 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

```

--------------------------------

### Create Vendor Refund (JSON Examples)

Source: https://docs.thredfi.com/api-reference/vendor-refunds/create-vendor-refund

Examples demonstrating how to structure JSON payloads for creating vendor refunds. These cover basic refunds, refunds with allocations for billing errors, and complete refunds including payment details.

```json
{
  "vendor_id": "uuid",
  "total_refunded_amount_cents": 15000,
  "currency": "GBP",
  "refund_type": "overpayment",
  "description": "Refund of overpayment"
}
```

```json
{
  "vendor_id": "uuid",
  "total_refunded_amount_cents": 50000,
  "currency": "GBP",
  "refund_type": "billing_error",
  "reference_number": "REF-12345",
  "allocations": [
    {
      "allocation_type": "bill",
      "bill_id": "bill-uuid",
      "amount_cents": 50000
    }
  ]
}
```

```json
{
  "vendor_id": "uuid",
  "total_refunded_amount_cents": 100000,
  "currency": "GBP",
  "external_id": "my-refund-123",
  "allocations": [
    {
      "allocation_type": "bill",
      "bill_id": "bill-uuid",
      "amount_cents": 100000
    }
  ],
  "payments": [
    {
      "refunded_amount_cents": 100000,
      "payment_method": "bank_transfer",
      "processor": "wise"
    }
  ]
}
```

--------------------------------

### List Chart of Accounts (Example Request)

Source: https://docs.thredfi.com/api-reference/chart-of-accounts/list-chart-of-accounts

Demonstrates how to construct a request to list chart of accounts with various filtering and grouping parameters. This example shows filtering by account type, fiscal year, and grouping by account type.

```http
GET /accounts?filter[account_type]=asset&filter[period_year]=2024&group_by=type&page[size]=20 HTTP/1.1
Host: api.thredfi.com
Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### Get Profit and Loss Report (OpenAPI)

Source: https://docs.thredfi.com/api-reference/reports/get-profit-and-loss

This OpenAPI definition describes the GET endpoint for retrieving a Profit and Loss report for a specific business. It supports filtering by date range and detail level, and returns summary metrics or a detailed breakdown of accounts. Authentication is handled via various JWT and Basic Auth methods.

```yaml
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/{business_id}/reports/profit-and-loss/:
    get:
      tags:
        - Reports
      summary: Get profit and loss report
      description: |
        Retrieve a Profit and Loss report for a business within a date range.

        **Important:** Both posted and draft journal entries are included in the calculations.

        **Summary metrics returned:**
        - net_revenue_cents: Sum of Revenue subtype accounts
        - total_operating_income_cents: Net revenue + Other Operating Income
        - gross_profit_cents: Total operating income - Direct Costs
        - operating_profit_cents: Gross profit - Operating Expenses
        - profit_before_tax_cents: Operating profit + Finance Income - Finance Costs
        - net_profit_cents: Profit before tax - Income Tax

        **Detail levels:**
        - `summary` (default): Returns only summary metrics
        - `detailed`: Returns summary + line item breakdown by AccountSubtype

        All values are in cents. Currency is the business's base currency.
      operationId: get_profit_and_loss
      parameters:
        - in: path
          name: business_id
          schema:
            type: string
            format: uuid
          description: Business UUID
          required: true
        - in: query
          name: detail_level
          schema:
            type: string
            enum:
              - detailed
              - summary
            default: summary
          description: 'Level of detail: ''summary'' or ''detailed'''
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: Report period end date (YYYY-MM-DD)
          required: true
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: Report period start date (YYYY-MM-DD)
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProfitAndLoss'
          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:
    ProfitAndLoss:
      type: object
      description: >-
        Complete P&L report response.


        Subtype group keys are AccountSubtype.value:

        - "revenue" (from Account.AccountSubtype.REVENUE.value)

        - "other_operating_income" (from
        Account.AccountSubtype.OTHER_OPERATING_INCOME.value)

        - etc.
      properties:
        business_id:
          type: string
          format: uuid
          description: Business UUID
        start_date:
          type: string
          format: date
          description: Report period start
        end_date:
          type: string
          format: date
          description: Report period end
        currency:
          type: string

```

--------------------------------

### GET /v1/platform/businesses/

Source: https://docs.thredfi.com/api-reference/business-management/list-businesses

Retrieves a list of all active businesses registered in the platform by the partner, with support for standardized pagination and filtering.

```APIDOC
## GET /v1/platform/businesses/

### Description
Returns a list of all active businesses registered in our platform by the partner with standardized pagination.

**Supported Countries**: EU/UK, Nordic, and APAC markets
- EU/UK/Nordic: GB, DE, FR, NL, ES, IT, IE, BE, AT, PT, SE, NO, DK, FI, IS
- APAC: MY, SG

**Supported Currencies**: GBP, EUR, USD, SEK, NOK, DKK, ISK, MYR, SGD

### Method
GET

### Endpoint
/v1/platform/businesses/

### Parameters
#### Query Parameters
- **country** (string) - Optional - Filter by country code (case-insensitive, e.g., GB, DE, FR, MY, SG)
- **entity_type** (string) - Optional - Filter by entity type (case-insensitive). Valid values depend on business country. Examples: limited, gmbh, bv, sl, etc.
- **is_archived** (boolean) - Optional - Filter by archived status (true/false)
- **legal_name** (string) - Optional - Filter by legal name (case-insensitive partial match)
- **page** (integer) - Optional - Page number (default: 1)
- **page_size** (integer) - Optional - Items per page (default: 20, max: 100)
- **search** (string) - Optional - Search in business name, legal name, external ID, VAT number, and company number

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **count** (integer) - Total number of items
- **page_info** (object) - Pagination details including total count, current page, total pages, and page size
- **results** (array) - An array of business objects
  - **id** (string) - Unique identifier for the business
  - **external_id** (string) - Partner-provided external identifier for the business
  - **name** (string) - Business name
  - **legal_name** (string) - Legal name of the business
  - **entity_type** (string) - Type of business entity
  - **country** (string) - Country code of the business
  - **province** (string) - Province or state of the business
  - **eu_nace_industry_code** (string) - EU NACE industry code
  - **is_active** (boolean) - Indicates if the business is active
  - **activation_at** (string) - Timestamp when the business was activated
  - **created_at** (string) - Timestamp when the business was created
  - **updated_at** (string) - Timestamp when the business was last updated
  - **vat_number** (string) - VAT number of the business
  - **company_number** (string) - Company registration number
  - **tax_id** (string) - Tax identification number
  - **base_currency** (string) - Base currency of the business

#### Response Example
```json
{
  "count": 123,
  "page_info": {
    "total_count": 123,
    "current_page": 1,
    "total_pages": 7,
    "page_size": 20
  },
  "results": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "external_id": "customer-123",
      "name": "Acme Coffee Ltd",
      "legal_name": "Acme Coffee Limited",
      "entity_type": "limited",
      "country": "GB",
      "province": "Greater London",
      "eu_nace_industry_code": "56.30",
      "is_active": true,
      "activation_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-20T14:22:00Z",
      "vat_number": "GB123456789",
      "company_number": "12345678",
      "tax_id": "1234567890",
      "base_currency": "GBP"
    }
  ]
}
```
```

--------------------------------

### Get a Customer

Source: https://docs.thredfi.com/api-reference/customers/get-customer

Retrieves the details of an existing customer using their unique identifier.

```APIDOC
## GET /customers/{customerId}

### Description
Retrieves the details of an existing customer.

### Method
GET

### Endpoint
/customers/{customerId}

### Parameters
#### Path Parameters
- **customerId** (string) - Required - The unique identifier of the customer to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the customer.
- **name** (string) - The name of the customer.
- **email** (string) - The email address of the customer.

#### Response Example
```json
{
  "id": "cust_12345",
  "name": "John Doe",
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### GET /v1/platform/businesses/{business_id}/

Source: https://docs.thredfi.com/api-reference/business-management/get-business

Retrieve details of a specific business using its unique identifier.

```APIDOC
## GET /v1/platform/businesses/{business_id}/

### Description
Retrieve details of a specific business.

### Method
GET

### Endpoint
/v1/platform/businesses/{business_id}/

### Parameters
#### Path Parameters
- **business_id** (string) - Required - A UUID string identifying this business.

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the business
- **external_id** (string) - Your unique identifier for this business
- **legal_name** (string) - 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) - 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) - Primary email address for the business
- **base_currency** (string) - Base currency for accounting (ISO 4217 code)
- **accounting_method** (string) - Accounting method: 'cash' or 'accrual'
- **fiscal_year_end** (string) - Fiscal year end date
- **activation_at** (string) - Date and time when the business was activated
- **is_active** (boolean) - Whether the business is active (false if archived)
- **created_at** (string) - Date and time when the business was created
- **updated_at** (string) - Date and time when the business was updated

#### Response Example
```json
{
  "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"
}
```
```

--------------------------------

### Authenticate and Fetch Customers using ThredFi API (Python, JavaScript, cURL)

Source: https://docs.thredfi.com/api-reference/authentication/get-business-token

Demonstrates how to authenticate with the ThredFi API to obtain a partner token, then a business-scoped token, and finally use the business token to retrieve customer data. This process involves making POST requests for token acquisition and a GET request for data retrieval. Ensure you have the 'requests' library installed for Python and 'axios' for Node.js. cURL examples require 'jq' for JSON parsing.

```python
import requests
import base64

# Step 1: Get partner token
partner_uuid = "123e4567-e89b-12d3-a456-426614174000"
api_key = "sk_live_abc123xyz789"
credentials = f"{partner_uuid}:{api_key}"
encoded = base64.b64encode(credentials.encode()).decode()

partner_response = requests.post(
    "https://sandbox.thredfi.com/v1/platform/oauth2/token/",
    headers={"Authorization": f"Basic {encoded}"},
    data={"grant_type": "client_credentials"}
)
partner_token = partner_response.json()["access_token"]

# Step 2: Get business-scoped token
business_id = "456e7890-e89b-12d3-a456-426614174111"
business_response = requests.post(
    f"https://sandbox.thredfi.com/v1/platform/{business_id}/oauth2/token/",
    headers={"Authorization": f"Bearer {partner_token}"}
)
business_token = business_response.json()["access_token"]

# Step 3: Use business token to access resources
customers = requests.get(
    f"https://sandbox.thredfi.com/v1/platform/businesses/{business_id}/customers/",
    headers={"Authorization": f"Bearer {business_token}"}
)
print(customers.json())
```

```javascript
const axios = require('axios');

async function authenticateAndFetchCustomers() {
  // Step 1: Get partner token
  const partnerUuid = '123e4567-e89b-12d3-a456-426614174000';
  const apiKey = 'sk_live_abc123xyz789';
  const encoded = Buffer.from(`${partnerUuid}:${apiKey}`).toString('base64');

  const partnerResponse = await axios.post(
    'https://sandbox.thredfi.com/v1/platform/oauth2/token/',
    new URLSearchParams({ grant_type: 'client_credentials' }),
    { headers: { 'Authorization': `Basic ${encoded}` } }
  );
  const partnerToken = partnerResponse.data.access_token;

  // Step 2: Get business-scoped token
  const businessId = '456e7890-e89b-12d3-a456-426614174111';
  const businessResponse = await axios.post(
    `https://sandbox.thredfi.com/v1/platform/${businessId}/oauth2/token/`,
    {},
    { headers: { 'Authorization': `Bearer ${partnerToken}` } }
  );
  const businessToken = businessResponse.data.access_token;

  // Step 3: Use business token to access resources
  const customers = await axios.get(
    `https://sandbox.thredfi.com/v1/platform/businesses/${businessId}/customers/`,
    { headers: { 'Authorization': `Bearer ${businessToken}` } }
  );

  console.log(customers.data);
}
```

```bash
# Step 1: Get partner token
PARTNER_TOKEN=$(curl -X POST https://sandbox.thredfi.com/v1/platform/oauth2/token/ \
  -H "Authorization: Basic $(echo -n 'YOUR_PARTNER_UUID:YOUR_API_KEY' | base64)" \
  -d "grant_type=client_credentials" | jq -r '.access_token')

# Step 2: Get business-scoped token
BUSINESS_ID="456e7890-e89b-12d3-a456-426614174111"
BUSINESS_TOKEN=$(curl -X POST https://sandbox.thredfi.com/v1/platform/$BUSINESS_ID/oauth2/token/ \
  -H "Authorization: Bearer $PARTNER_TOKEN" | jq -r '.access_token')

# Step 3: Use business token
curl https://sandbox.thredfi.com/v1/platform/businesses/$BUSINESS_ID/customers/ \
  -H "Authorization: Bearer $BUSINESS_TOKEN"
```

--------------------------------

### POST /v1/platform/businesses/

Source: https://docs.thredfi.com/api-reference/business-management/create-business

Creates a new business with idempotency support. If a business with the same external_id already exists, the existing business is returned.

```APIDOC
## POST /v1/platform/businesses/

### Description
Create a new business with idempotency support via external_id. 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.

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

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

### Method
POST

### Endpoint
/v1/platform/businesses/

### Parameters
#### Request Body
- **external_id** (string) - Required - Unique identifier for the business.
- **legal_name** (string) - Required - The legal name of the business.
- **entity_type** (string) - Required - The type of legal entity (e.g., 'limited', 'gmbh').
- **email** (string) - Required - The primary email address for the business.
- **country** (string) - Optional - The country code of the business (e.g., 'GB', 'DE').
- **base_currency** (string) - Optional - The base currency for the business (e.g., 'GBP', 'EUR').
- **phone_number** (string) - Optional - The phone number of the business.
- **vat_number** (string) - Optional - The VAT number of the business.
- **company_number** (string) - Optional - The company registration number.
- **province** (string) - Optional - The province or state of the business.
- **accounting_method** (string) - Optional - The accounting method used ('accrual' or 'cash').
- **fiscal_year_end** (string) - Optional - The fiscal year end date (YYYY-MM-DD).
- **metadata** (object) - Optional - Additional metadata for the business.

### Request Example
```json
{
  "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"
  }
}
```

### Response
#### Success Response (201 Created or 200 OK for idempotency)
- **id** (string) - Unique identifier for the business.
- **external_id** (string) - The external identifier provided.
- **legal_name** (string) - The legal name of the business.
- **name** (string) - The display name of the business.
- **entity_type** (string) - The type of legal entity.
- **phone_number** (string) - The phone number.
- **tin** (string) - Tax Identification Number.
- **vat_number** (string) - VAT number.
- **company_number** (string) - Company registration number.
- **country** (string) - Country code.
- **province** (string) - Province or state.
- **eu_nace_industry_code** (string) - NACE industry code.
- **email** (string) - Email address.
- **base_currency** (string) - Base currency.
- **accounting_method** (string) - Accounting method.
- **fiscal_year_end** (string) - Fiscal year end date.
- **activation_at** (string) - Timestamp when the business was activated.
- **is_active** (boolean) - Indicates if the business is active.
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.
- **metadata** (object) - Additional metadata.

#### Response Example
```json
{
  "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"
  }
}
```

#### Error Responses
- **400 Bad Request**: Validation errors in request data.
- **401 Unauthorized**: Authentication required - missing or invalid API key.
- **403 Forbidden**: Permission denied - insufficient privileges.
```

--------------------------------

### Get Account Journal Entry Lines

Source: https://docs.thredfi.com/api-reference/chart-of-accounts/get-account-entries

Fetches paginated journal entry lines for the account, including opening and closing balances, running balance per line item, and source document types. Supports filtering by start and end dates.

```APIDOC
## GET /accounts/{accountId}/journal_entry_lines

### Description
Returns paginated journal entry lines for the account with running balance. The response includes the opening balance, closing balance, running balance per line item, and the source document type for each entry.

### Method
GET

### Endpoint
/accounts/{accountId}/journal_entry_lines

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The ID of the account to retrieve journal entry lines for.

#### Query Parameters
- **start_date** (string) - Optional - Filter entries from this date (inclusive). Format: YYYY-MM-DD.
- **end_date** (string) - Optional - Filter entries up to this date (inclusive). Format: YYYY-MM-DD.

### Request Example
```
GET /accounts/123e4567-e89b-12d3-a456-426614174000/journal_entry_lines?start_date=2023-01-01&end_date=2023-12-31
```

### Response
#### Success Response (200)
- **opening_balance_cents** (integer) - Balance at the start of the period or account inception.
- **closing_balance_cents** (integer) - Balance at the end of the period or current balance.
- **journal_entry_lines** (array) - A list of journal entry line items.
  - **id** (string) - The unique identifier for the journal entry line.
  - **entry_date** (string) - The date the journal entry was created.
  - **description** (string) - A description of the journal entry.
  - **amount_cents** (integer) - The amount of the journal entry in cents.
  - **running_balance_cents** (integer) - The running balance after this entry.
  - **source_document_type** (string) - The type of the source document (e.g., "invoice", "payment").

#### Response Example
```json
{
  "opening_balance_cents": 100000,
  "closing_balance_cents": 150000,
  "journal_entry_lines": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "entry_date": "2023-01-15",
      "description": "Invoice #INV-001",
      "amount_cents": 50000,
      "running_balance_cents": 150000,
      "source_document_type": "invoice"
    },
    {
      "id": "f0e9d8c7-b6a5-4321-0987-654321fedcba",
      "entry_date": "2023-01-20",
      "description": "Payment Received",
      "amount_cents": -20000,
      "running_balance_cents": 130000,
      "source_document_type": "payment"
    }
  ]
}
```
```

--------------------------------

### Create Business (Idempotent)

Source: https://docs.thredfi.com/api-reference/business-management/create-business

Creates a new business with idempotency support. If a business with the same external_id already exists for your partner, the existing business is returned.

```APIDOC
## POST /businesses

### Description
Creates a new business with idempotency support via `external_id`. 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 a `_meta` field indicating creation vs. idempotent return.

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

### Method
POST

### Endpoint
/businesses

### Parameters
#### Request Body
- **external_id** (string) - Required - A unique identifier for the business provided by the partner.
- **legal_name** (string) - Required - The legal name of the business.
- **entity_type** (string) - Required - The type of business entity (e.g., 'company', 'sole_trader'). Validation depends on the country.
- **email** (string) - Required - The primary email address for the business.

### Request Example
```json
{
  "external_id": "partner-business-123",
  "legal_name": "Example Corp",
  "entity_type": "company",
  "email": "contact@example.com"
}
```

### Response
#### Success Response (200 or 201)
- **_meta** (object) - Metadata about the response, including whether the business was created or returned idempotently.
- **id** (string) - The unique identifier for the business within Thredfi.
- **external_id** (string) - The partner-provided external ID.
- **legal_name** (string) - The legal name of the business.
- **entity_type** (string) - The type of business entity.
- **email** (string) - The primary email address for the business.

#### Response Example
```json
{
  "_meta": {
    "created": true 
  },
  "id": "biz_abc123",
  "external_id": "partner-business-123",
  "legal_name": "Example Corp",
  "entity_type": "company",
  "email": "contact@example.com"
}
```
```

--------------------------------

### API Request: Get Cash Flow Statement (Summary)

Source: https://docs.thredfi.com/api-reference/schemas/cash-flow-statement

Example API endpoint to retrieve a summary-level Cash Flow Statement for a specified date range. This call returns only section totals and the cash reconciliation.

```http
GET /v1/.../reports/cash-flow/?start_date=2024-01-01&end_date=2024-12-31&detail_level=summary
```

--------------------------------

### Retrieve Balance Sheet - Summary Detail Level API

Source: https://docs.thredfi.com/api-reference/schemas/balance-sheet

An example API GET request to fetch the Balance Sheet report with a 'summary' detail level. This endpoint returns only the calculated totals for assets, liabilities, and equity.

```http
GET /v1/.../reports/balance-sheet/?as_of_date=2024-12-31&detail_level=summary
```

--------------------------------

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

Source: https://docs.thredfi.com/api-reference/customers/create-customer

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

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

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

### Method
POST

### Endpoint
/v1/platform/businesses/{business_id}/customers/

### Parameters
#### Path Parameters
- **business_id** (string) - Required - Business UUID provided by Thred (unique identifier for the business)

#### Request Body
- **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) - 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) - Optional - Whether customer is exempt from tax/VAT (defaults to false)
- **status** (string) - Enum: active, archived

### Request Example
```json
{
  "external_id": "cust_123",
  "reference_number": "REF456",
  "individual_name": "John Doe",
  "email": "john.doe@example.com",
  "address_line1": "123 Main St",
  "city": "Anytown",
  "postal_code": "12345",
  "country": "US"
}
```

### Response
#### Success Response (201)
- **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
- **company_name** (string) - Registered company name
- **email** (string) - 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
- **tax_exempt** (boolean) - Whether customer is exempt from tax/VAT
- **status** (string) - Current status of the customer (active or archived)

#### Response Example
```json
{
  "external_id": "cust_123",
  "reference_number": "REF456",
  "individual_name": "John Doe",
  "company_name": null,
  "email": "john.doe@example.com",
  "mobile_phone": null,
  "office_phone": null,
  "address_line1": "123 Main St",
  "address_line2": null,
  "city": "Anytown",
  "state_county": null,
  "postal_code": "12345",
  "country": "US",
  "vat_number": null,
  "tax_exempt": false,
  "status": "active"
}
```
```

--------------------------------

### Retrieve Balance Sheet - Detailed Level API

Source: https://docs.thredfi.com/api-reference/schemas/balance-sheet

An example API GET request to fetch the Balance Sheet report with a 'detailed' detail level. This endpoint returns totals along with a line item breakdown by account subtype.

```http
GET /v1/.../reports/balance-sheet/?as_of_date=2024-12-31&detail_level=detailed
```

--------------------------------

### API Request: Get Cash Flow Statement (Detailed)

Source: https://docs.thredfi.com/api-reference/schemas/cash-flow-statement

Example API endpoint to retrieve a detailed Cash Flow Statement for a specified date range. This call includes section totals and individual account line items.

```http
GET /v1/.../reports/cash-flow/?start_date=2024-01-01&end_date=2024-12-31&detail_level=detailed
```