Skip to content

API reference

Screen customers

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)Required
  • namestringRequired
  • categorystringRequired

    A tag the loop uses to keep customers of one kind apart; empty when none.

  • policyobjectRequired

    The loop rules the customer sets. A rule that is not set is null, and means no rule.

    Show child attributesHide child attributes
    • sharePctintegerRequiredNullable

      The most of a loop its ads take.

    • playsPerHourintegerRequiredNullable

      At most this many plays an hour.

    • playsPerDayintegerRequiredNullable

      At most this many plays a day.

  • selfSeparatebooleanRequired

    Whether the customer’s own ads are kept apart in the loop.

  • bookingsintegerRequired

    Bookings that name the customer.

  • liveintegerRequired

    Those with a file on a screen now.

  • plays30dintegerRequired

    Plays of its bookings in the last 30 days. A play names no customer; this follows each booking’s current customer.

  • archivedbooleanRequired
  • importedFromstringRequired

    The screen system the customer was brought across from, if any.

    Possible valuesdoohlybroadsign

  • createdAtstring (date-time)Required
  • createdBystringRequired

    The member who made it; empty when it came from Mestra Network or an import.

List all screen customers

PermissionScreens · 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.

Query parameters

  • qstringOptional

    Only customers whose name has this text, whatever the capitals.

  • archivedstringOptional

    1 includes archived customers. They are left out otherwise.

    Possible values1

  • afterstringOptional

    The next of the previous page.

  • limitintegerOptional

    Customers in the page, 1 to 200; 50 when left out.

    Default50

Returns

A page of customers.

Returns a list of Screen customer objects.

Errors

StatusCodeMeaning
400

limit is not a number from 1 to 200.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key (the key or role can’t do this).

404not_connected

not_connected.

409api_offintegration_off

api_off, or integration_off (Mestra screens are off and the organisation has no Mestra Network).

Create a screen customer

PermissionScreens · 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).

Body parameters

  • namestringRequired

    1 to 200 characters. Unique in the organisation, whatever its capitals.

  • categorystringOptional

    Up to 64 characters. Customers with the same category are kept apart in the loop.

  • policyobjectOptional

    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.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • selfSeparatebooleanOptional

    Keep the customer’s own ads apart in the loop.

Returns

The customer.

Returns the Screen customer object.

Errors

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

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_keyscreens_limitedplan_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.

404not_connected

not_connected.

409name_takenapi_offintegration_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).

List all screen customer categories

PermissionScreens · 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:

  • categoriesarray of stringsRequired

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key (the key or role can’t do this).

404not_connected

not_connected.

409api_offintegration_off

api_off, or integration_off (Mestra screens are off and the organisation has no Mestra Network).

Retrieve a screen customer

PermissionScreens · Read

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

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key (the key or role can’t do this).

404unknown_customer

unknown_customer: no such customer, or one of another organisation.

409api_offintegration_off

api_off, or integration_off (Mestra screens are off and the organisation has no Mestra Network).

Update a screen customer

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required

Body parameters

  • namestringOptional

    1 to 200 characters. Unique in the organisation, whatever its capitals.

  • categorystringOptional

    Up to 64 characters. Customers with the same category are kept apart in the loop. Empty clears it.

  • policyobjectOptional

    Loop rules. A rule left out stays as it is; null clears it.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • selfSeparatebooleanOptional

    Keep the customer’s own ads apart in the loop.

Returns

The customer.

Returns the Screen customer object.

Errors

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

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_keyscreens_limitedplan_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.

404unknown_customer

unknown_customer: no such customer, or one of another organisation.

409name_takenapi_offintegration_off

name_taken, api_off, or integration_off (Mestra screens are off and the organisation has no Mestra Network).

502network_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.

Update a screen customer to archived

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required

Returns

The customer, archived.

Returns the Screen customer object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_keyscreens_limitedplan_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.

404unknown_customer

unknown_customer: no such customer, or one of another organisation.

409api_offintegration_off

api_off, or integration_off (Mestra screens are off and the organisation has no Mestra Network).

502network_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.

Update a screen customer to restored

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required

Returns

The customer, restored.

Returns the Screen customer object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_keyscreens_limitedplan_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.

404unknown_customer

unknown_customer: no such customer, or one of another organisation.

409removed_in_networkapi_offintegration_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).

502network_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.