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

# Business Entity Types

> Country-specific business entity type validation rules

## Validation Logic

Thred validates `entity_type` based on the business's `country`:

* **Restricted countries** (GB, DE, NL, ES, BE): Must use predefined business entity type codes
* **All other countries**: Accept any string value for `entity_type`

***

## Business Entity Types by Country

For these countries, the API will reject requests with invalid business entity types (HTTP 400).

<Tabs>
  <Tab title="United Kingdom (GB)">
    **Valid business entity types:**

    | Code          | Description                   |
    | ------------- | ----------------------------- |
    | `limited`     | Ltd (Private Limited Company) |
    | `sole_trader` | Sole Trader                   |
    | `llp`         | Limited Liability Partnership |
    | `partnership` | Partnership                   |
    | `plc`         | Public Limited Company        |

    **Example:**

    ```json theme={null}
    {
      "entity_type": "limited",
      "country": "GB",
      "legal_name": "Acme Ltd"
    }
    ```
  </Tab>

  <Tab title="Germany (DE)">
    **Valid business entity types:**

    | Code                | Description                                  |
    | ------------------- | -------------------------------------------- |
    | `gmbh`              | GmbH (Gesellschaft mit beschränkter Haftung) |
    | `ug`                | UG (haftungsbeschränkt) - Mini-GmbH          |
    | `ag_de`             | AG (Aktiengesellschaft)                      |
    | `einzelunternehmen` | Einzelunternehmen (Sole Proprietorship)      |
    | `gbr`               | GbR (Gesellschaft bürgerlichen Rechts)       |
    | `kg`                | KG (Kommanditgesellschaft)                   |
    | `ohg`               | OHG (Offene Handelsgesellschaft)             |

    **Example:**

    ```json theme={null}
    {
      "entity_type": "gmbh",
      "country": "DE",
      "legal_name": "Beispiel GmbH"
    }
    ```
  </Tab>

  <Tab title="Netherlands (NL)">
    **Valid business entity types:**

    | Code          | Description                     |
    | ------------- | ------------------------------- |
    | `bv`          | BV (Besloten vennootschap)      |
    | `eenmanszaak` | Eenmanszaak / ZZP               |
    | `vof`         | VOF (Vennootschap onder firma)  |
    | `cv`          | CV (Commanditaire vennootschap) |
    | `nv`          | NV (Naamloze vennootschap)      |
    | `vve`         | VvE (Vereniging van Eigenaars)  |

    **Example:**

    ```json theme={null}
    {
      "entity_type": "bv",
      "country": "NL",
      "legal_name": "Voorbeeld BV"
    }
    ```
  </Tab>

  <Tab title="Spain (ES)">
    **Valid business entity types:**

    | Code             | Description                         |
    | ---------------- | ----------------------------------- |
    | `sl`             | SL (Sociedad Limitada)              |
    | `slu`            | SLU (Sociedad Limitada Unipersonal) |
    | `sa_es`          | SA (Sociedad Anónima)               |
    | `autonomo`       | Autónomo (Empresario individual)    |
    | `sociedad_civil` | Sociedad Civil                      |

    **Example:**

    ```json theme={null}
    {
      "entity_type": "sl",
      "country": "ES",
      "legal_name": "Ejemplo SL"
    }
    ```
  </Tab>

  <Tab title="Belgium (BE)">
    **Valid business entity types:**

    | Code               | Description                         |
    | ------------------ | ----------------------------------- |
    | `self_employed_be` | Self-employed / sole trader         |
    | `bv_be`            | BV / SRL (Private limited company)  |
    | `nv_be`            | NV / SA (Public limited company)    |
    | `cv_be`            | CV / SC (Cooperative company)       |
    | `vof_be`           | VOF / SNC (General partnership)     |
    | `commv_be`         | CommV / SComm (Limited partnership) |
    | `vzw_be`           | VZW / ASBL (Non-profit association) |

    **Example:**

    ```json theme={null}
    {
      "entity_type": "bv_be",
      "country": "BE",
      "legal_name": "Voorbeeld BV"
    }
    ```
  </Tab>
</Tabs>

***

## Validation Behavior

### Cross-Field Validation

The API validates `entity_type` against `country` in create operations, and against the business's existing country in update operations:

**Create Business:**

```bash theme={null}
POST /v1/platform/businesses/
{
  "entity_type": "gmbh",
  "country": "GB"  # ❌ FAILS - German type in UK
}
```

**Update Business:**

```bash theme={null}
PATCH /v1/platform/businesses/{id}/
{
  "entity_type": "limited"  # Validates against business's existing country
}
```

### Error Response

Invalid business entity types return HTTP 400 with details:

```json theme={null}
{
  "error_code": "validation_error",
  "detail": "Invalid entity_type 'gmbh' for country GB. Valid options: limited (Ltd (Private Limited Company)), sole_trader (Sole Trader), llp (Limited Liability Partnership (LLP)), partnership (Partnership), plc (Public Limited Company (PLC))"
}
```

***

## Edge Cases

<AccordionGroup>
  <Accordion title="Blank entity_type">
    The `entity_type` field is optional (`blank=True`). Omitting it or passing an empty string is valid for all countries.

    ```json theme={null}
    {
      "legal_name": "My Business",
      "country": "GB",
      "entity_type": ""  // ✅ Valid
    }
    ```
  </Accordion>

  <Accordion title="Case sensitivity">
    Business entity type codes are **case-insensitive**. The API automatically normalizes them to lowercase:

    * ✅ `"limited"` → stored as `"limited"`
    * ✅ `"Limited"` → stored as `"limited"`
    * ✅ `"LIMITED"` → stored as `"limited"`
    * ✅ `"GMBH"` → stored as `"gmbh"`

    **Recommendation**: Use lowercase for consistency, but any case will work.
  </Accordion>

  <Accordion title="Updating country">
    `country` is not a partner-mutable field on `PATCH /v1/platform/businesses/{id}/`.

    To change the legal country for an existing business, contact Thred support or create a new business record with a new `external_id` if the change represents a new legal entity.

    ```bash theme={null}
    # Business created with entity_type="limited", country="GB"
    PATCH /v1/platform/businesses/{id}/
    {
      "country": "DE"  # ❌ Not accepted by the partner update contract
    }
    ```
  </Accordion>
</AccordionGroup>