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

# Onboarding a Business

> Create your first business in Thred

When a user signs up for accounting in your platform, create a corresponding business in Thred.

<Steps>
  <Step title="Prepare business information">
    Collect the required data from your user:

    **Required fields:**

    * `external_id` - Your stable internal user/business ID (used for idempotency)
    * `legal_name` - Business legal name
    * `entity_type` - Business entity type ([validation depends on country](/implementation/entity-types))
    * `email` - Business contact email

    <Note>
      **Business entity type validation:** GB, DE, NL, ES, and BE require specific business entity type codes. All other countries accept any value.

      [See complete business entity type reference](/implementation/entity-types)
    </Note>

    **Optional fields:**

    * `country` - ISO 2-letter code such as `NL`, `GB`, or `DE`
    * `base_currency` - ISO currency code such as `EUR`, `GBP`, or `USD`
    * `accounting_method` - `accrual` or `cash`
    * `company_number` - Company registration number
    * `vat_number` - VAT/tax ID
    * `coa_language` - Chart of accounts language such as `en` or `nl`
    * `metadata` - Partner-specific JSON metadata
  </Step>

  <Step title="Call the Create Business API">
    POST to [`/v1/platform/businesses/`](/api-reference/business-management/create-business) with a partner-scoped token:

    ```bash theme={null}
    POST https://sandbox.thredfi.com/v1/platform/businesses/
    Authorization: Bearer {partner_token}
    ```

    Example payload:

    ```json theme={null}
    {
      "external_id": "customer-12345",
      "legal_name": "Acme Solutions B.V.",
      "entity_type": "bv",
      "email": "accounting@acme.example",
      "country": "NL",
      "base_currency": "EUR",
      "accounting_method": "accrual",
      "vat_number": "NL123456789B01",
      "company_number": "12345678",
      "coa_language": "en"
    }
    ```

    [See Create Business API endpoint](/api-reference/business-management/create-business)
  </Step>

  <Step title="Store the business_id">
    Save the returned `business_id` in your database:

    ```json theme={null}
    {
      "id": "964f4325-3efb-400d-a1bd-8b1f29e828cf",
      "external_id": "customer-12345",
      "legal_name": "Acme Solutions B.V.",
      "entity_type": "bv",
      "country": "NL",
      "base_currency": "EUR",
      "is_active": true
    }
    ```

    Map this to your user record:

    ```python theme={null}
    user.thred_business_id = response["id"]
    user.save()
    ```
  </Step>

  <Step title="Get business-scoped token">
    Exchange your partner token for a business-scoped token:

    ```bash theme={null}
    POST https://sandbox.thredfi.com/v1/platform/{business_id}/oauth2/token/
    Authorization: Bearer {partner_token}
    ```

    Store the returned token for API calls and frontend SDK.

    [See Authentication guide](/implementation/authentication)
  </Step>
</Steps>

***

## Idempotency

<Tip>
  Use `external_id` to prevent duplicate businesses.

  If you retry with the same `external_id`, Thred returns the existing business instead of creating a new one. This is safe for network failures and retries.
</Tip>

***

## What Happens After Creation

Thred automatically:

1. Sets up chart of accounts (based on business entity type and country)
2. Initializes accounting periods
3. Creates default tax configurations
4. Prepares the accounting UI for embedding

Your user can now access the embedded accounting interface.

***

Business created. Now [set up authentication](/implementation/authentication) to secure API access.