> ## Documentation Index
> Fetch the complete documentation index at: https://docs.my-virtual-office.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Customer

> Create a new customer for your My Virtual Office account

# Create Customer

Create a new customer associated with your seller account.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your API key. Can also be provided via `Authorization: Bearer` header.
</ParamField>

## Request Body

<ParamField body="first_name" type="string" required>
  Customer's first name. Maximum 100 characters.
</ParamField>

<ParamField body="last_name" type="string" required>
  Customer's last name. Maximum 100 characters.
</ParamField>

<ParamField body="email" type="string" required>
  Customer's email address. Must be a valid email format and unique for your account.
</ParamField>

<ParamField body="company_name" type="string">
  Company name. Maximum 200 characters.
</ParamField>

<ParamField body="legal_entity" type="string">
  Legal entity type (e.g., "GmbH", "LLC"). Maximum 100 characters.
</ParamField>

<ParamField body="language" type="string" default="de">
  Preferred language for communications. Must be either `en` or `de`.
</ParamField>

<ParamField body="status" type="string" default="active">
  Customer status. Must be one of `active`, `inactive`, or `suspended`. Inactive or suspended customers cannot log in to the portal.
</ParamField>

<ParamField body="address_data" type="object">
  Customer's address information.

  <Expandable title="address_data properties">
    <ParamField body="street" type="string">
      Street address. Maximum 200 characters.
    </ParamField>

    <ParamField body="city" type="string">
      City name. Maximum 100 characters.
    </ParamField>

    <ParamField body="postal_code" type="string">
      Postal/ZIP code. Maximum 20 characters.
    </ParamField>

    <ParamField body="country" type="string">
      Country name or code. Maximum 100 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="postal_redirect_address" type="object">
  Address to which postal mail should be forwarded for this customer.

  <Expandable title="postal_redirect_address properties">
    <ParamField body="street" type="string">
      Street address. Maximum 200 characters.
    </ParamField>

    <ParamField body="city" type="string">
      City name. Maximum 100 characters.
    </ParamField>

    <ParamField body="postal_code" type="string">
      Postal/ZIP code. Maximum 20 characters.
    </ParamField>

    <ParamField body="country" type="string">
      Country name or code. Maximum 100 characters.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the customer (UUID)
</ResponseField>

<ResponseField name="seller_id" type="string">
  Your seller account ID (UUID)
</ResponseField>

<ResponseField name="first_name" type="string">
  Customer's first name
</ResponseField>

<ResponseField name="last_name" type="string">
  Customer's last name
</ResponseField>

<ResponseField name="email" type="string">
  Customer's email address
</ResponseField>

<ResponseField name="company_name" type="string | null">
  Company name if provided
</ResponseField>

<ResponseField name="legal_entity" type="string | null">
  Legal entity type if provided
</ResponseField>

<ResponseField name="language" type="string | null">
  Preferred language
</ResponseField>

<ResponseField name="address_data" type="object | null">
  Address information if provided
</ResponseField>

<ResponseField name="postal_redirect_address" type="object | null">
  Postal redirect address if set
</ResponseField>

<ResponseField name="status" type="string">
  Customer status (`active`, `inactive`, or `suspended`)
</ResponseField>

<ResponseField name="source" type="string">
  Source of customer creation (will be "api" for API-created customers)
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the customer was created
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of when the customer was last updated
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app-api.my-virtual-office.com/api/customers \
    -H "X-API-Key: sk_live_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "company_name": "Acme Inc",
      "legal_entity": "GmbH",
      "language": "de",
      "address_data": {
        "street": "Musterstraße 123",
        "city": "Berlin",
        "postal_code": "10115",
        "country": "Germany"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://app-api.my-virtual-office.com/api/customers', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      first_name: 'John',
      last_name: 'Doe',
      email: 'john.doe@example.com',
      company_name: 'Acme Inc',
      legal_entity: 'GmbH',
      language: 'de',
      address_data: {
        street: 'Musterstraße 123',
        city: 'Berlin',
        postal_code: '10115',
        country: 'Germany',
      },
    }),
  });

  const customer = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app-api.my-virtual-office.com/api/customers',
      headers={
          'X-API-Key': 'sk_live_your_api_key_here',
          'Content-Type': 'application/json',
      },
      json={
          'first_name': 'John',
          'last_name': 'Doe',
          'email': 'john.doe@example.com',
          'company_name': 'Acme Inc',
          'legal_entity': 'GmbH',
          'language': 'de',
          'address_data': {
              'street': 'Musterstraße 123',
              'city': 'Berlin',
              'postal_code': '10115',
              'country': 'Germany',
          },
      }
  )

  customer = response.json()
  ```
</CodeGroup>

## Example Response

```json 201 Created theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "seller_id": "660e8400-e29b-41d4-a716-446655440001",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "company_name": "Acme Inc",
  "legal_entity": "GmbH",
  "language": "de",
  "address_data": {
    "street": "Musterstraße 123",
    "city": "Berlin",
    "postal_code": "10115",
    "country": "Germany"
  },
  "postal_redirect_address": null,
  "status": "active",
  "source": "api",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}
```

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "Bad Request",
    "message": "body must have required property 'email'"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "API key is required. Provide it via X-API-Key header or Authorization Bearer token."
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 403 Forbidden theme={null}
  {
    "error": "Forbidden",
    "message": "Customer limit reached. Your plan allows 10 customers."
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 409 Conflict theme={null}
  {
    "error": "Conflict",
    "message": "A customer with this email already exists"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Code | Error                 | Description                                       |
| --------- | --------------------- | ------------------------------------------------- |
| 400       | Bad Request           | Invalid request body or missing required fields   |
| 401       | Unauthorized          | Missing or invalid API key                        |
| 403       | Forbidden             | Customer limit reached for your subscription      |
| 409       | Conflict              | Email address already exists for another customer |
| 500       | Internal Server Error | Unexpected server error                           |