Create Customer

curl --request POST \
  --url https://app-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>"
  }
}
'

import requests

url = "https://app-api.my-virtual-office.com/api/customers"

payload = {
    "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>"
    }
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
    }
  })
};

fetch('https://app-api.my-virtual-office.com/api/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app-api.my-virtual-office.com/api/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app-api.my-virtual-office.com/api/customers"

	payload := strings.NewReader("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"legal_entity\": \"<string>\",\n  \"language\": \"<string>\",\n  \"status\": \"<string>\",\n  \"address_data\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"postal_redirect_address\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app-api.my-virtual-office.com/api/customers")
  .header("X-API-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"legal_entity\": \"<string>\",\n  \"language\": \"<string>\",\n  \"status\": \"<string>\",\n  \"address_data\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"postal_redirect_address\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app-api.my-virtual-office.com/api/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"legal_entity\": \"<string>\",\n  \"language\": \"<string>\",\n  \"status\": \"<string>\",\n  \"address_data\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"postal_redirect_address\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

POST

api

customers

Create Customer

curl --request POST \
  --url https://app-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>"
  }
}
'

import requests

url = "https://app-api.my-virtual-office.com/api/customers"

payload = {
    "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>"
    }
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
    }
  })
};

fetch('https://app-api.my-virtual-office.com/api/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app-api.my-virtual-office.com/api/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app-api.my-virtual-office.com/api/customers"

	payload := strings.NewReader("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"legal_entity\": \"<string>\",\n  \"language\": \"<string>\",\n  \"status\": \"<string>\",\n  \"address_data\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"postal_redirect_address\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app-api.my-virtual-office.com/api/customers")
  .header("X-API-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"legal_entity\": \"<string>\",\n  \"language\": \"<string>\",\n  \"status\": \"<string>\",\n  \"address_data\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"postal_redirect_address\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app-api.my-virtual-office.com/api/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"legal_entity\": \"<string>\",\n  \"language\": \"<string>\",\n  \"status\": \"<string>\",\n  \"address_data\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"postal_redirect_address\": {\n    \"street\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

Create Customer

Create a new customer associated with your seller account.

Authentication

string

required

Your API key. Can also be provided via Authorization: Bearer header.

Request Body

string

required

Customer’s first name. Maximum 100 characters.

string

required

Customer’s last name. Maximum 100 characters.

string

required

Customer’s email address. Must be a valid email format and unique for your account.

string

Company name. Maximum 200 characters.

string

Legal entity type (e.g., “GmbH”, “LLC”). Maximum 100 characters.

string

default:"de"

Preferred language for communications. Must be either en or de.

string

default:"active"

Customer status. Must be one of active, inactive, or suspended. Inactive or suspended customers cannot log in to the portal.

object

Customer’s address information.

Show address_data properties

string

Street address. Maximum 200 characters.

string

City name. Maximum 100 characters.

string

Postal/ZIP code. Maximum 20 characters.

string

Country name or code. Maximum 100 characters.

object

Address to which postal mail should be forwarded for this customer.

Show postal_redirect_address properties

string

Street address. Maximum 200 characters.

string

City name. Maximum 100 characters.

string

Postal/ZIP code. Maximum 20 characters.

string

Country name or code. Maximum 100 characters.

Response

string

Unique identifier for the customer (UUID)

string

Your seller account ID (UUID)

string

Customer’s first name

string

Customer’s last name

string

Customer’s email address

string | null

Company name if provided

string | null

Legal entity type if provided

string | null

Preferred language

object | null

Address information if provided

object | null

Postal redirect address if set

string

Customer status (active, inactive, or suspended)

string

Source of customer creation (will be “api” for API-created customers)

string

ISO 8601 timestamp of when the customer was created

string

ISO 8601 timestamp of when the customer was last updated

Example Request

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"
    }
  }'

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();

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()

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

​Create Customer

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Error Codes

Create Customer

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Error Codes