# Screen customers

A screen customer is an advertiser that bookings can name. A customer can set its own loop rules, and is listed with how many bookings and plays it has. A customer that is archived keeps its history and can be restored. See [Customers](https://withmestra.com/docs/player/customers/) for the guide.

A screen customer is an advertiser that bookings can name. A customer can set its own loop rules, and is listed with how many bookings and plays it has. A customer that is archived keeps its history and can be restored. See [Customers](https://withmestra.com/docs/player/customers/) for the guide.

## The Screen customer object

A customer (advertiser) that bookings can name: its category, the loop rules it sets, and how many bookings and plays it has.

- `id` (string (uuid), required):
- `name` (string, required):
- `category` (string, required): A tag the loop uses to keep customers of one kind apart; empty when none.
- `policy` (object, required): The loop rules the customer sets. A rule that is not set is `null`, and means no rule.
  - `sharePct` (integer, required, nullable): The most of a loop its ads take.
  - `playsPerHour` (integer, required, nullable): At most this many plays an hour.
  - `playsPerDay` (integer, required, nullable): At most this many plays a day.
- `selfSeparate` (boolean, required): Whether the customer's own ads are kept apart in the loop.
- `bookings` (integer, required): Bookings that name the customer.
- `live` (integer, required): Those with a file on a screen now.
- `plays30d` (integer, required): Plays of its bookings in the last 30 days. A play names no customer; this follows each booking's current customer.
- `archived` (boolean, required):
- `importedFrom` (string, required): The screen system the customer was brought across from, if any. One of: \`\`, `doohly`, `broadsign`.
- `createdAt` (string (date-time), required):
- `createdBy` (string, required): The member who made it; empty when it came from Mestra Network or an import.

```json
{
  "id": "string",
  "name": "string",
  "category": "string",
  "policy": {
    "sharePct": 0,
    "playsPerHour": 0,
    "playsPerDay": 0
  },
  "selfSeparate": false,
  "bookings": 0,
  "live": 0,
  "plays30d": 0,
  "archived": false,
  "importedFrom": "",
  "createdAt": "string",
  "createdBy": "string"
}
```

## List all screen customers

`GET /api/v1/player/customers`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. The customers (advertisers) that bookings can name, listed by name (capitals ignored), 50 to a page unless `limit` says otherwise, with the loop rules each sets and how many bookings and plays it has. A rule that is not set is `null`. Archived customers are left out unless you ask for them. A customer that is also a Mestra Network customer is the same record in both.

### Parameters

- `q` (string, optional): Only customers whose name has this text, whatever the capitals.
- `archived` (string, optional): `1` includes archived customers. They are left out otherwise. One of: `1`.
- `after` (string, optional): The `next` of the previous page.
- `limit` (integer, optional): Customers in the page, 1 to 200; 50 when left out.

### Returns

A page of customers.

### Errors

- 400: `limit` is not a number from 1 to 200.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key` (the key or role can't do this).
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off`, or `integration_off` (Mestra screens are off and the organisation has no Mestra Network).

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/customers \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Create a screen customer

`POST /api/v1/player/customers`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Makes a customer for bookings to name. `name` is 1 to 200 characters and is one for each name in the organisation, whatever its capitals (an archived customer keeps its name). `category` is up to 64 characters; customers with the same category are kept apart in the loop. `policy` sets the customer's loop rules: `sharePct` (1 to 100) is the most of a loop its ads take, and `playsPerHour` and `playsPerDay` (1 or more) are the most plays an hour and a day; a rule that is `null` or left out is not set. `selfSeparate` keeps the customer's own ads apart in the loop. A key limited to some screens can't make a customer (403 `screens_limited`).

### Parameters

- `name` (string, required): 1 to 200 characters. Unique in the organisation, whatever its capitals.
- `category` (string, optional): Up to 64 characters. Customers with the same category are kept apart in the loop.
- `policy` (object, optional): Loop rules: `sharePct` is the most of a loop the customer's ads take (1 to 100); `playsPerHour` and `playsPerDay` are the most plays an hour and a day (1 or more). A rule that is `null` or left out is not set.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `selfSeparate` (boolean, optional): Keep the customer's own ads apart in the loop.

### Returns

The customer.

### Errors

- 400: A value out of range: `name` is empty or over 200 characters, `category` over 64, `policy.sharePct` not 1 to 100, `policy.playsPerHour` or `policy.playsPerDay` under 1.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`, `plan_refused`): `wrong_key` (the key or role can't do this), `screens_limited` (a key limited to some screens can't make, change or archive a customer; reading customers is allowed), or `plan_refused`.
- 404 (`not_connected`): `not_connected`.
- 409 (`name_taken`, `api_off`, `integration_off`): `name_taken` (another customer has that name, whatever its capitals), `api_off`, or `integration_off` (Mestra screens are off and the organisation has no Mestra Network).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/customers \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Bolt Energy","category":"Energy","policy":{"sharePct":25,"playsPerHour":60},"selfSeparate":true}'
```

## List all screen customer categories

`GET /api/v1/player/customers/categories`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. The categories in use by active customers.

### Returns

The categories.

An object with:

- `categories` (array of strings, required):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key` (the key or role can't do this).
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off`, or `integration_off` (Mestra screens are off and the organisation has no Mestra Network).

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/customers/categories \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a screen customer

`GET /api/v1/player/customers/{id}`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. One customer, archived or not.

### Parameters

- `id` (string (uuid), required):

### Returns

The customer.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key` (the key or role can't do this).
- 404 (`unknown_customer`): `unknown_customer`: no such customer, or one of another organisation.
- 409 (`api_off`, `integration_off`): `api_off`, or `integration_off` (Mestra screens are off and the organisation has no Mestra Network).

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/customers/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update a screen customer

`PATCH /api/v1/player/customers/{id}`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Changes a customer's name, category, loop rules or whether its own ads are kept apart. Send only what changes. In `policy`, a rule left out stays as it is and `null` clears it. A customer that is also a Mestra Network customer is the same record in both. You can change its name, category and rules here, and the change shows in Mestra Network too; if Mestra Network could not be updated the change still stands here and the call answers 502 `network_not_synced`. A `name` another customer already has, whatever its capitals, is 409 `name_taken`.

### Parameters

- `id` (string (uuid), required):
- `name` (string, optional): 1 to 200 characters. Unique in the organisation, whatever its capitals.
- `category` (string, optional): Up to 64 characters. Customers with the same category are kept apart in the loop. Empty clears it.
- `policy` (object, optional): Loop rules. A rule left out stays as it is; `null` clears it.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `selfSeparate` (boolean, optional): Keep the customer's own ads apart in the loop.

### Returns

The customer.

### Errors

- 400: A value out of range: `name` is empty or over 200 characters, `category` over 64, `policy.sharePct` not 1 to 100, `policy.playsPerHour` or `policy.playsPerDay` under 1.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`, `plan_refused`): `wrong_key` (the key or role can't do this), `screens_limited` (a key limited to some screens can't make, change or archive a customer; reading customers is allowed), or `plan_refused`.
- 404 (`unknown_customer`): `unknown_customer`: no such customer, or one of another organisation.
- 409 (`name_taken`, `api_off`, `integration_off`): `name_taken`, `api_off`, or `integration_off` (Mestra screens are off and the organisation has no Mestra Network).
- 502 (`network_not_synced`): `network_not_synced`: the customer is also a Mestra Network customer and the change was saved here, but Mestra Network's copy could not be updated. The change stands; save again to retry.

### Example request

```sh
curl --request PATCH \
  --url https://app.withmestra.com/api/v1/player/customers/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"policy":{"playsPerHour":null,"sharePct":30}}'
```

## Update a screen customer to archived

`POST /api/v1/player/customers/{id}/archive`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Takes a customer off the pick-list; its bookings keep it and keep playing. A customer that is also a Mestra Network customer is the same record in both. If Mestra Network could not be updated the customer is archived here all the same and the call answers 502 `network_not_synced`.

### Parameters

- `id` (string (uuid), required):

### Returns

The customer, archived.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`, `plan_refused`): `wrong_key` (the key or role can't do this), `screens_limited` (a key limited to some screens can't make, change or archive a customer; reading customers is allowed), or `plan_refused`.
- 404 (`unknown_customer`): `unknown_customer`: no such customer, or one of another organisation.
- 409 (`api_off`, `integration_off`): `api_off`, or `integration_off` (Mestra screens are off and the organisation has no Mestra Network).
- 502 (`network_not_synced`): `network_not_synced`: the customer is also a Mestra Network customer and the change was saved here, but Mestra Network's copy could not be updated. The change stands; save again to retry.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/customers/string/archive \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update a screen customer to restored

`POST /api/v1/player/customers/{id}/unarchive`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Puts an archived customer back on the pick-list. A customer that was removed in Mestra Network can't be unarchived here: the call answers 409 `removed_in_network`. If Mestra Network could not be updated the customer is restored here all the same and the call answers 502 `network_not_synced`.

### Parameters

- `id` (string (uuid), required):

### Returns

The customer, restored.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`, `plan_refused`): `wrong_key` (the key or role can't do this), `screens_limited` (a key limited to some screens can't make, change or archive a customer; reading customers is allowed), or `plan_refused`.
- 404 (`unknown_customer`): `unknown_customer`: no such customer, or one of another organisation.
- 409 (`removed_in_network`, `api_off`, `integration_off`): `removed_in_network` (the customer was removed in Mestra Network and can't be unarchived here), `api_off`, or `integration_off` (Mestra screens are off and the organisation has no Mestra Network).
- 502 (`network_not_synced`): `network_not_synced`: the customer is also a Mestra Network customer and the change was saved here, but Mestra Network's copy could not be updated. The change stands; save again to retry.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/customers/string/unarchive \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
