---
title: "Customer Management"
slug: "customer-management"
updated: 2026-07-09T05:07:49Z
published: 2026-07-09T05:07:49Z
canonical: "help.frisbii.com/customer-management"
---

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

# Customer Management

Before starting a checkout or checking access rights, Frisbii Media needs to know who the customer is. If you manage users in your own system (external user management), you create or retrieve the customer via the API using your own user ID as a reference.

---

## Create or retrieve a customer

The `POST /customers` endpoint is idempotent: if a customer with the given `customerId` already exists, it is returned unchanged. No duplicate is created.

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.frisbii-media.com/api/v3.0/']);
$userData = [
    'customerId' => "4711",             // your internal numeric user ID
    'email'      => "user@example.com", // used for login and communication
    'language'   => 'de',               // two-char ISO language code
];
$response = $client->request('POST', 'customers', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => $userData,
]);
$customer = json_decode($response->getBody()->getContents());
// $customer->customerId is the Frisbii Media customer ID to use in subsequent calls
```

---

## customerId vs. externalSystemId

Frisbii Media supports two ways to reference your internal user:

| Field | Type | When to use |
| --- | --- | --- |
| `customerId` | Numeric string | Your internal user ID is numeric (e.g. `"4711"`) |
| `externalSystemId` | Alphanumeric string | Your internal user ID is a UUID or other non-numeric format (e.g. `"550e8400-e29b-41d4-a716-446655440000"`) |

Both fields are unique within your Frisbii Media company. Use whichever matches your existing ID format — you do not need both.

---

## Full customer payload (all available fields)

The minimal payload for a checkout requires only `customerId` (or `externalSystemId`), `email`, and `language`. The following shows all available fields, used primarily when importing customers:

```php
$customerData = [
    'email'              => "kitty.miller@company.com", // login email, must be unique
    'invoiceEmail'       => "office@company.com",       // used only for invoice emails
    'username'           => "kitty_207",                // must be unique in Frisbii Media
    'pseudoEmail'        => false,   // set true to auto-generate a pseudo email for customers without one
    'salutation'         => "MR",    // one of: NONE, MRS, MR, DIVERSE
    'firstName'          => "Kitty",
    'lastName'           => "Miller",
    'birthday'           => "2000-07-20T00:00:00.000Z",
    'language'           => "de",
    'registrationSource' => "Import-" . (new DateTime())->format('Y-m-d'),
    'customerId'         => "12345",                              // numeric, unique
    'externalSystemId'   => "550e8400-e29b-41d4-a716-446655440000", // alphanumeric, unique
];
$customer = json_decode($client->request('POST', '/customers', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => $customerData,
])->getBody()->getContents(), true);
```

> [!NOTE]
> `pseudoEmail`**:** Set to `true` when importing customers who do not have an email address. Frisbii Media will generate a placeholder email internally. These customers cannot log in via SSO until they connect a real email address (see [SSO: Advanced Options – loginIdentifier](/frisbii-media/docs/sso-advanced-options#loginidentifier-connecting-imported-accounts)).

---

## Retrieve a customer by email

To look up an existing customer without creating one:

```php
$response = $client->request('GET', "customers?email={$email}", [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
]);
$customer = json_decode($response->getBody()->getContents())?->items[0] ?? null;
```

---