Skip to main content
POST
/
api
/
customers
Create Customer
curl --request POST \
  --url https://api.my-virtual-office.com/api/customers \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "company_name": "<string>",
  "legal_entity": "<string>",
  "language": "<string>",
  "status": "<string>",
  "address_data": {
    "street": "<string>",
    "city": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "postal_redirect_address": {
    "street": "<string>",
    "city": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  }
}
'
{
  "error": "Bad Request",
  "message": "body must have required property 'email'"
}

​
Create Customer

Create a new customer associated with your seller account.

​
Authentication

​
X-API-Key
string
required
Your API key. Can also be provided via Authorization: Bearer header.

​
Request Body

​
first_name
string
required
Customer’s first name. Maximum 100 characters.
​
last_name
string
required
Customer’s last name. Maximum 100 characters.
​
email
string
required
Customer’s email address. Must be a valid email format and unique for your account.
​
company_name
string
Company name. Maximum 200 characters.
​
legal_entity
string
Legal entity type (e.g., “GmbH”, “LLC”). Maximum 100 characters.
​
language
string
default:"de"
Preferred language for communications. Must be either en or de.
​
status
string
default:"active"
Customer status. Must be one of active, inactive, or suspended. Inactive or suspended customers cannot log in to the portal.
​
address_data
object
Customer’s address information.
​
postal_redirect_address
object
Address to which postal mail should be forwarded for this customer.

​
Response

​
id
string
Unique identifier for the customer (UUID)
​
seller_id
string
Your seller account ID (UUID)
​
first_name
string
Customer’s first name
​
last_name
string
Customer’s last name
​
email
string
Customer’s email address
​
company_name
string | null
Company name if provided
​
legal_entity
string | null
Legal entity type if provided
​
language
string | null
Preferred language
​
address_data
object | null
Address information if provided
​
postal_redirect_address
object | null
Postal redirect address if set
​
status
string
Customer status (active, inactive, or suspended)
​
source
string
Source of customer creation (will be “api” for API-created customers)
​
created_at
string
ISO 8601 timestamp of when the customer was created
​
updated_at
string
ISO 8601 timestamp of when the customer was last updated

​
Example Request

curl -X POST https://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"
    }
  }'

​
Example Response

201 Created
{
  "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

{
  "error": "Bad Request",
  "message": "body must have required property 'email'"
}

{
  "error": "Unauthorized",
  "message": "API key is required. Provide it via X-API-Key header or Authorization Bearer token."
}

{
  "error": "Forbidden",
  "message": "Customer limit reached. Your plan allows 10 customers."
}

{
  "error": "Conflict",
  "message": "A customer with this email already exists"
}

​
Error Codes

HTTP CodeErrorDescription
400Bad RequestInvalid request body or missing required fields
401UnauthorizedMissing or invalid API key
403ForbiddenCustomer limit reached for your subscription
409ConflictEmail address already exists for another customer
500Internal Server ErrorUnexpected server error