Admin Customer Management

Create, search, and manage customer records from the admin API.

For general conventions, see JSON-API Conventions. For authentication, see Authentication.

Prerequisites

A valid Bearer token with admin access
Organization context (?o={organization_id})

Customer vs. Customer Account

The platform distinguishes between two entities:

Entity	Scope	Purpose
Customer	Per-organization	A business record with contact info, bookings, and custom fields. Owned by a specific organization.
Customer Account	Global (platform-wide)	An end-user identity that can log in. Linked to `Customer` records across multiple organizations via `account_id`.

A single person may have multiple Customer records (one per organization they interact with), all linked to the same CustomerAccount.

Creating a Customer

POST /api/v1/customers?o={org_id}

{
  "data": {
    "type": "customers",
    "attributes": {
      "given_name": "Jane",
      "family_name": "Doe",
      "email": "jane@example.com",
      "mobile": "+49 170 1234567",
      "company": "Acme Corp",
      "locale": "de-DE"
    }
  }
}

Key Attributes

Attribute	Type	Description
`given_name`	string	First name
`family_name`	string	Last name
`email`	string	Email address
`mobile`	string	Mobile phone number
`phone`	string	Landline phone number
`company`	string	Company name
`sex`	string	Gender
`birth_date`	string	Date of birth (Y-m-d)
`locale`	string	Preferred language (defaults to organization locale)

Finding Customers

By Email (Exact Match)

GET /api/v1/customers?o={org_id}&filter[email]=jane@example.com

By Search (Fuzzy)

Searches across name, email, and phone:

GET /api/v1/customers?o={org_id}&filter[search]=jane

By Custom Field

See the custom field filter syntax in JSON-API Conventions.

Resolving a Customer by Code

Look up a customer from a QR code, barcode, or account pass:

GET /api/v1/customers/resolve-code?o={org_id}&code={identifier_code}

Resolves the code via the ModelIdentifier system and returns the associated customer resource.

Creating Custom Model Identifiers

To assign a custom identifier (barcode, member number, etc.) to a customer, create a model-identifier linked to the customer:

POST /api/v1/model-identifiers?o={org_id}

{
  "data": {
    "type": "model-identifiers",
    "attributes": {
      "code": "MEMBER-12345",
      "type": "custom"
    },
    "relationships": {
      "identifiable": {
        "data": {
          "type": "customers",
          "id": "{customer_uuid}"
        }
      }
    }
  }
}

Once created, the customer can be looked up using resolve-code with the assigned code. You can also view a customer's existing identifiers via the model-identifiers relationship:

GET /api/v1/customers/{customer_id}/model-identifiers?o={org_id}

Merging Duplicate Customers

Combine two customer records into one:

POST /api/v1/customers/{source_customer_id}/merge?o={org_id}

{
  "referenceId": "{target_customer_uuid}"
}

The merge process:

Fills empty fields on the target customer from the source (name, phone, birth date, etc.)
Merges custom field data (target values take priority on conflicts)
Transfers all relationships (bookings, orders, invoices) to the target
Links the global account if the source had one and the target doesn't
Deletes the source customer record

Warning: This operation is irreversible. The source customer is permanently deleted.

Removing a Customer from a Community

GET /api/v1/customers/{customer_id}/remove-from-community?o={org_id}&community_id={community_uuid}

Removes the customer's membership from the specified community.

Exporting Customers

Trigger an asynchronous export:

POST /api/v1/exports?o={org_id}

{
  "data": {
    "type": "exports",
    "attributes": {
      "type": "customers",
      "filters": {
        "search": "jane"
      }
    }
  }
}

The export is processed in the background. Retrieve the download URL from the export resource once complete.

Common Errors

Error	Cause	Solution
`422` — email already exists	Duplicate email in organization	Use search to find the existing record, or merge
`404` — code not found	Invalid identifier code	Verify the code belongs to this organization
`422` — merge reference not found	Invalid target customer UUID	Verify the target customer exists

Invoices

Booking Calendars