API reference
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 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.
Attributes
idstring (uuid)RequirednamestringRequiredcategorystringRequiredA tag the loop uses to keep customers of one kind apart; empty when none.
policyobjectRequiredThe loop rules the customer sets. A rule that is not set is
null, and means no rule.Show child attributesHide child attributes
sharePctintegerRequiredNullableThe most of a loop its ads take.
playsPerHourintegerRequiredNullableAt most this many plays an hour.
playsPerDayintegerRequiredNullableAt most this many plays a day.
selfSeparatebooleanRequiredWhether the customer’s own ads are kept apart in the loop.
bookingsintegerRequiredBookings that name the customer.
liveintegerRequiredThose with a file on a screen now.
plays30dintegerRequiredPlays of its bookings in the last 30 days. A play names no customer; this follows each booking’s current customer.
archivedbooleanRequiredimportedFromstringRequiredThe screen system the customer was brought across from, if any.
Possible values
doohlybroadsigncreatedAtstring (date-time)RequiredcreatedBystringRequiredThe member who made it; empty when it came from Mestra Network or an import.
List all screen customers
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.
Query parameters
qstringOptionalOnly customers whose name has this text, whatever the capitals.
archivedstringOptional1includes archived customers. They are left out otherwise.Possible values
1afterstringOptionalThe
nextof the previous page.limitintegerOptionalCustomers in the page, 1 to 200; 50 when left out.
Default
50
Returns
A page of customers.
Returns a list of Screen customer objects.
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
Create a screen customer
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).
Body parameters
namestringRequired1 to 200 characters. Unique in the organisation, whatever its capitals.
categorystringOptionalUp to 64 characters. Customers with the same category are kept apart in the loop.
policyobjectOptionalLoop rules:
sharePctis the most of a loop the customer’s ads take (1 to 100);playsPerHourandplaysPerDayare the most plays an hour and a day (1 or more). A rule that isnullor left out is not set.Show child attributesHide child attributes
sharePctintegerOptionalNullableplaysPerHourintegerOptionalNullableplaysPerDayintegerOptionalNullable
selfSeparatebooleanOptionalKeep the customer’s own ads apart in the loop.
Returns
The customer.
Returns the Screen customer object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A value out of range: | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limitedplan_refused |
|
404 | not_connected |
|
409 | name_takenapi_offintegration_off |
|
List all screen customer categories
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:
categoriesarray of stringsRequired
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
Retrieve a screen customer
Needs the Screens read permission; any member’s session (a viewer too) will do. One customer, archived or not.
Path parameters
idstring (uuid)Required
Returns
The customer.
Returns the Screen customer object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_customer |
|
409 | api_offintegration_off |
|
Update a screen customer
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.
Path parameters
idstring (uuid)Required
Body parameters
namestringOptional1 to 200 characters. Unique in the organisation, whatever its capitals.
categorystringOptionalUp to 64 characters. Customers with the same category are kept apart in the loop. Empty clears it.
policyobjectOptionalLoop rules. A rule left out stays as it is;
nullclears it.Show child attributesHide child attributes
sharePctintegerOptionalNullableplaysPerHourintegerOptionalNullableplaysPerDayintegerOptionalNullable
selfSeparatebooleanOptionalKeep the customer’s own ads apart in the loop.
Returns
The customer.
Returns the Screen customer object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A value out of range: | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limitedplan_refused |
|
404 | unknown_customer |
|
409 | name_takenapi_offintegration_off |
|
502 | network_not_synced |
|
Update a screen customer to archived
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.
Path parameters
idstring (uuid)Required
Returns
The customer, archived.
Returns the Screen customer object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limitedplan_refused |
|
404 | unknown_customer |
|
409 | api_offintegration_off |
|
502 | network_not_synced |
|
Update a screen customer to restored
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.
Path parameters
idstring (uuid)Required
Returns
The customer, restored.
Returns the Screen customer object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limitedplan_refused |
|
404 | unknown_customer |
|
409 | removed_in_networkapi_offintegration_off |
|
502 | network_not_synced |
|