Skip to main content

Wallboard API Documentation (1.11)

Download OpenAPI specification:Download

API Support: support@wallboard.us

OpenAPI specification (OAS) for the Wallboard API.

Wallboard has hundreds of endpoints and documenting all of them takes time. If you have any question please contact our support and we'll extend the documentation on-demand, based on your needs.

Overview

In this document, you can find some useful information about the Wallboard API. The API mainly follows the REST approach with OAuth 2.0 authentication and authorization standards.

Wallboard have two types of end-points:

Public

  • Callable by any client
  • API root starts with /public-api/
  • No OAuth2 authorization
  • Usually used with GUID based ID-s

Secured

  • Only callable with OAuth2 authorization
  • API root starts with /api/

Notes

  • The API only uses JSON format for data transfer objects.
  • The update logic usually follows the “if an attribute is null, it’s ignored” logic.
  • In the return value if a primitive attribute is not present it means NULL.

Generally available parameters

customerId - tenant selector parameter

  • Customer ID parameter is present on most our endpoints and it can be used to select a specific tenant in the system, which the operations should be performed on.
  • This is used by ADMIN users (or network/subresellers OWNERS) as they have access to multiple tenants.
  • Non-admin users don't have to fill this parameter, because they can only access their customer's resources.
  • If as an ADMIN you want to get every resource in the system set this value to "-1".

page,size - pagination parameters

  • Pagination is implemented by the default Spring pagination logic.
  • Page index starts from 0.
  • If you don’t set any additional parameter, the API gives back the first 20 elements.

sort parameter

  • Spring's default sort expression
  • Directions: asc, desc
  • Multiple parameters are supported - sort=name,asc&sort=lastActivity,desc
  • There is no escape logic, the parameter simply has to be URL encoded.
  • Value selectors can be chained with a . to be able to access embedded or connected entities' attributes
  • Examples: sort=name,asc, sort=content.name,asc

search - filtering parameter

With this parameter you can create dynamic queries to filter the resources.

select - selecting fields

With this parameter you can specify which attributes or related entities should be present in the response.

Syntax (WBQL - Wallboard Query Language)

Search (WBCriteria)

Value operators

  • : - means contains in case of string literals and equals in case of other value types
    • Example: name:mydevice - matches for prefix-mydevice-postfix
  • = - means exact match
  • - not equals
    • Unicode escape sequence: \u2260
  • - not contains
    • Works only with string literals
    • Unicode escape sequence: \u2209
  • ^ - starts with
    • Works only with string literals
  • > - greater than
  • - greater than or equal
    • Unicode escape sequence: \2265
  • < - less than
  • - less than or equal
    • Unicode escape sequence: \2264

Logical operators

  • , - AND
    • Example: name=a,name=b
  • | - OR
    • Example: name=something|name=something else
  • Logical groupings are currently not supported

Value matcher keywords

  • true
    • Only can be used with boolean attributes
    • Example: isValid:true
  • false
    • Only can be used with boolean attributes
  • NULL - value or connected entity is null
    • Example: content=NULL
  • !NULL - value or connected entity is NOT null
    • Example: folder.parent=!NULL

Escaping

  • All values has to be URL encoded
  • The search parameter value must be URL encoded (most libraries encode request parameters by default)
  • Format: search=urlEncode({value_name}{value_operator}urlEncode({value}))
  • Example: search=name:mydevice:athome (the second : is part of the device's name) -> search=name%3Amydevice%253Aathome

Notes

  • Date type attributes are supported and can be matched by UTC timestamps (milliseconds)
    • Example: startDate>1683616562 - means the startDate should be after 2023-05-09T07:15:46+00:00
  • Value selectors can be chained with a . to be able to access embedded or connected entities' attributes
    • Example: deviceGroup.parent.id=000c08d294df48efb1b0f5aa754d7ef9 - meaning: the device's group's parent group's id should be '000c08d294df48efb1b0f5aa754d7ef9'.

Basic Examples

  • User name contains the letter a: name:a
  • Device state is online and is in emergency state: state:ONLINE,device.emergencyStatus:true
  • A device content's name contains the substring "happy new year": content.name:happy new year

Advanced Examples

  • Coming soon

Select (WBSelect)

With the select parameter you can also specify attributes that you want to select from a given entity. This method allows you to run more optimal and faster queries.

You can use the select function to append attributes from other related entities to the query (if the relationship is one-to-one or many-to-one).

Syntax:

  • * : Selects all primitive attributes of the entity
    • Equivalent to the missing select parameter
    • Calculated fields and related entities are NOT included
    • Example: select=*
  • , : Attributes should be separated with a ,
    • Example: select=id,name,comment
  • ( ) : Used to select specific attributes from related entities
    • Example: select=id,name,device(id,name)

Advanced examples:

  • select=*,customer(id,name)
    • Selects all primitive attributes from the device, plus the id and name of the customer it belongs to
  • select=*,totalUserLoginCount,lastDeviceActivity
    • Select all the primitive attributes from the customer and the two specified calculated fields

Team management

includeReadOnlyInfo parameter

  • Most of the GET endpoints support the optional calculation of the readOnly-ness of a resource
  • An entity can be read-only for a user depending on the team settings
  • If specifically not needed we suggest to turn if off, for faster response times

includeResourcesWithoutTeam parameter

  • Determines whether or not to include resources which are not assigned to any team

selectTeamIds parameter

  • A list of team ids that resources should be included in the response
  • If empty, all team's resources are included

Roles

All users have a role and all of the secured API requires a minimum role to use it. The role is always hierarchical, so a user with an OWNER role can use all endpoints that require an OWNER or lower roles. We use the following hierarchy:

Global:

  • ADMIN
    • Super admin of the system.
    • Can access anything and can do everything.

Tenant:

  • OWNER
    • Tenant(customer) admin.
    • Under it's own domain can access anything and can do everything.
    • Can't belong to any team.
  • TECHNICIAN
    • Can do everything except user and team management.
  • APPROVER
  • EDITOR
  • CONTRIBUTOR
  • VIEWER

Terminology

We are using a bit different terminology for entities like you used to in our GUI. The following expressions mean the same:

  • device = screen = player
  • customer = client = tenant
  • subreseller = network owner

Swagger - Deprecated

We have swagger set up at https://development.wallboard.info/swagger-ui.html, but it's not perfectly configured, there can be missing or misleading parameters. Also, the microservice's API is missing from there.

Authentication

OAuth2 client credentials

By default, there are two built-in client credentials in the system, which you can use to get an access_token.

Default client details:

  • client-id: default-client
  • client-secret: 76211db5d8ea
  • Basic auth header value: Basic ZGVmYXVsdC1jbGllbnQ6NzYyMTFkYjVkOGVh
  • access_token validity: 20 minutes
  • refresh_token validity: 30 days

Short-lived client details:

  • client-id: short-lived
  • client-secret: mPSjfsJy8rs4m7y4
  • Basic auth header value: Basic c2hvcnQtbGl2ZWQ6bVBTamZzSnk4cnM0bTd5NA==
  • access_token validity: 20 minutes
  • refresh_token validity: 30 minutes

JWT

Certain new API endpoints use JWT token as authorization instead of the regular access_token.

token

OAuth2 token management operations

Get and refresh access token

To log in (get first access_token) fill username/password and set grant_type to "password".

To exchange a refresh_token for a new access_token fill refresh_token parameter and set grant_type to "refresh_token".

header Parameters
Authorization
required
string <Basic clientId:clientSecret>
Example: Basic ZGVmYXVsdC1jbGllbnQ6NzYyMTFkYjVkOGVh

Uses basic authentication. The 'clientId:clientSecret' part must be base64 encoded.

Request Body schema: x-www-form-urlencoded
required
username
string <username@example.com>

Email address of the user who wants to log in.

password
string

Password of the user who wants to log in.

refresh_token
string

Refresh token of the user who already logged in.

grant_type
string
Enum: "password" "refresh_token"

On login use "password", on refresh use "refresh_token".

Responses

Request samples

curl -X POST \
  https://example.com/oauth/token \
  -H 'Authorization: Basic ZGVmYXVsdC1jbGllbnQ6NzYyMTFkYjVkOGVh' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'username=user@example.com' \
  --data-urlencode 'password=MyPassword123'

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_total_validity_seconds": 0,
  • "jwt_access_token": "string",
  • "customer_id": 0
}

device

Device management

Upload a preview image for a device

Upload a preview image for a device. This api always response with status OK.

query Parameters
deviceId
required
string

ID of the device

highRes
boolean
Default: false

Indicates whether the image is high resolution or not

header Parameters
Content-Type
required
string <multipart/form-data; boundary={boundary}>
Example: multipart/form-data; boundary=q1w2e3r4t5y6u7i8o9
Request Body schema: multipart/form-data
image
any <binary>

Responses

Request samples

Content type
multipart/form-data
--q1w2e3r4t5y6u7i8o9
Content-Disposition: form-data; name=image; filename="image.jpg"
Content-Type: image/jpg

{..binary_data_of_picture..}

Get devices with basic attributes

Minimum role: VIEWER

Useful for listing or if quick response time is required and you only need the id and name.

Authorizations:
token_auth
query Parameters
customerId
integer (customerId)
search
string (search)

WBQL search expression

page
integer (page)
Default: 0

Page index

size
integer (size)
Default: 20

Size of page

sort
string (sort)

Sort expression

includeReadOnlyInfo
boolean (includeReadOnlyInfo)
Default: false

Whether or not the readOnly attribute should be filled on the response

includeResourcesWithoutTeam
boolean (includeResourcesWithoutTeam)
Default: true
selectTeamIds
Array of strings (selectTeamIds)
Example: selectTeamIds={team_id_1},{team_id_2}

Responses

Request samples

curl -X POST "https://example.com/api/device/simplePaged?customerId=123&page=0&size=20&sort=name,asc" \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "content": [
    ]
}

Register device

A device calls it every time it turned on or reconnects to the network

The deviceInfo parameter should be a stringified JSON object Example:

{
  "other":{
    "brand":"beta",
    "debug":false,
    "locked":false,
    "lastStartTime":"2023-10-18T00:01:11.467Z",
    "firmwareStatus":"UNKNOWN",
    "webViewVersion":"Chrome/87"
  },
  "general":{
    "model":"HD223",
    "version":"4.1.510",
    "hostname":"BrightSign-33E84S001174",
    "platform":"BRIGHTSIGN",
    "fwVersion":"9.0.105",
    "osVersion":"7.0.21",
    "versionCode":"JsCore",
    "serialNumber":"33E84S001183",
    "webResolution":"1440x900",
    "nativeResolution":"1440x900"
  },
  "metrics":{
    "cpu":{
      "cores":1,
      "threads":1,
      "description":"ARMv7 Processor rev 3 (v7l)"
    },
    "screen":[
      {
        "used":true,
        "scaling":1,
        "resolution":"1440x900",
        "displayName":""
      }
    ],
    "network":[
      {
        "ip":"192.168.1.53",
        "mac":"90:ac:3f:10:13:99",
        "name":"eth",
        "type":"eth"
      }
    ],
    "storage":[
      {
        "type":"internal",
        "mount":"/storage/sd",
        "capacity":31914459136
      }
    ],
    "maxMemory":482344960
  }
}
Request Body schema: application/json
required
deviceId
string
deviceInfo
string
type
string
Enum: "TABLET" "PHONE" "SCREEN" "DESKTOP"
platform
string
Enum: "ANDROID" "WINDOWS" "BRIGHTSIGN" "SAMSUNG" "LG" "PWA" "UNKNOWN"
object

optional

fillContentDetails
boolean
Default: true

optional

Responses

Request samples

Content type
application/json
{
  • "deviceId": "string",
  • "deviceInfo": "string",
  • "type": "TABLET",
  • "platform": "ANDROID",
  • "supportedFeatures": {
    },
  • "fillContentDetails": true
}

Response samples

Content type
application/json
{
  • "content": "string",
  • "deviceName": "string",
  • "showName": true,
  • "showConsole": true,
  • "showDeviceInfo": true,
  • "showStateIndicator": true,
  • "dataRowId": "string",
  • "datasourceId": "string",
  • "emergencyState": true,
  • "sensorConfig": "string",
  • "updateVersionUpperLimit": "string",
  • "rebootTime": "string",
  • "timeStamp": 0,
  • "licenseType": "BASIC",
  • "weatherLocation": "string",
  • "volumeLevel": 0,
  • "brightnessLevel": 0,
  • "displayStatus": "ON",
  • "locked": true,
  • "timeZone": "string",
  • "syncPeriodMillis": 0,
  • "rotation": {
    },
  • "tags": [
    ],
  • "advancedConfiguration": { },
  • "updateRule": { },
  • "workingHours": { },
  • "connectionSettings": { },
  • "statisticsSettings": { },
  • "resourcesToCache": {
    }
}

Refresh content on device

Minimum role: APPROVER

Authorizations:
token_auth
query Parameters
customerId
integer (customerId)
search
string
applyOn
required
string (applyOn)
Enum: "DEVICE" "DEVICEGROUP" "ALL"

Defines what search expression will applied to.

Responses

Request samples

curl -X POST \
  https://example.com/api/v2/device/refreshContent?customerId=123&search=id%3A000c08d294df48efb1b0f5aa754d7ef9&applyOn=DEVICE \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json'    

Assign a device to a customer

Minimum role: TECHNICIAN

Authorizations:
token_auth
query Parameters
customerId
integer
Request Body schema: application/json
required
customerId
string
activationCode
string
serial
string
deviceName
string
deviceGroupId
string
contentId
string
emergencyContentId
string
licenseOrderId
integer
showName
boolean
Default: false
showConsole
boolean
Default: false
weatherLocation
string
timeZone
string
object
tags
array of strings <= 10 items
emergencyStatus
boolean
Default: false
updateVersionUpperLimit
string
rebootTime
string
volumeLevel
integer
brightnessLevel
integer
advancedConfiguration
object
updateRule
object
datasourceId
string
daraRowId
string
sensorConfig
string
migrateFromDeviceId
string
deleteMigratedDevice
boolean
Default: false
object

Request samples

Content type
application/json
{
  • "customerId": "string",
  • "activationCode": "string",
  • "serial": "string",
  • "deviceName": "string",
  • "deviceGroupId": "string",
  • "contentId": "string",
  • "emergencyContentId": "string",
  • "licenseOrderId": 0,
  • "showName": false,
  • "showConsole": false,
  • "weatherLocation": "string",
  • "timeZone": "string",
  • "rotation": {
    },
  • "tags": null,
  • "emergencyStatus": false,
  • "updateVersionUpperLimit": "string",
  • "rebootTime": "string",
  • "volumeLevel": 0,
  • "brightnessLevel": 0,
  • "advancedConfiguration": { },
  • "updateRule": { },
  • "datasourceId": "string",
  • "daraRowId": "string",
  • "sensorConfig": "string",
  • "migrateFromDeviceId": "string",
  • "deleteMigratedDevice": false,
  • "resourceCreationTeamAssignParams": {
    }
}

file

Upload file

Minimum role: EDITOR

RFC 1867 compliant multipart/form-data stream (https://www.ietf.org/rfc/rfc1867.txt)

For pictures the thumbnails are created automatically by the server, but video files require and explicitly uploaded preview.

Authorizations:
token_auth
query Parameters
customerId
integer (customerId)
teamIds
string <{teamId},{readOnly},{teamId},{readOnly}... > (teamIds)
Example: teamIds=000c08d294df48efb1b0f5aa754d7ef9,true,00a22e86602c4a88914614aa9516a481,false
parentId
string

Folder ID where the file will be uploaded. If empty, the file will be uploaded into the root folder.

validFrom
integer <Epoch Unix timestamp in milliseconds.> (unix_timestamp)
Example: validFrom=1683802510

File validity start time.

validTo
integer <Epoch Unix timestamp in milliseconds.> (unix_timestamp)
Example: validTo=1683802510

File validity end time.

header Parameters
Content-Type
required
string <multipart/form-data; boundary={boundary}>
Example: multipart/form-data; boundary=q1w2e3r4t5y6u7i8o9
Request Body schema: multipart/form-data
files
Array of strings <binary> [ items <binary > ]
previews
Array of strings <binary> [ items <binary > ]

Responses

Request samples

Content type
multipart/form-data
--q1w2e3r4t5y6u7i8o9
Content-Disposition: form-data; name=files; filename="my_picture.png"
Content-Type: image/png

{..binary_data_of_picture..}
--q1w2e3r4t5y6u7i8o9
Content-Disposition: form-data; name=previews; filename="my_video_preview.preview"
Content-Type: video/mp4

{..binary_data_of_video_preview..}
--q1w2e3r4t5y6u7i8o9--

Response samples

Content type
application/json
[
  • {
    }
]

datasource

Update INTERNAL datasource's data

Minimum role: TECHNICIAN

Authorizations:
token_auth
path Parameters
datasourceId
string
Request Body schema: application/json
required
data
string <{\"example_key\" : \"example_value\"}>

In Wallboard all datasources mapped to JSON format in the end. Hence, the value of this field should be a stringified JSON.

Responses

Request samples

Content type
application/json
{
  • "data": "string"
}

Response samples

Content type
application/json
{
  • "timestamp": 1683802510,
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "path": "string",
  • "exception": "string",
  • "details": { }
}

Get datasource resource

Public API for accessing datasource resources.

This API allows you to retrieve specific resources from a datasource identified by its ID. You can specify the JSON path to the desired resource and the response type too (JSON or file).

JSONPath standard: https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html
JSONPath tester: https://jsonpath.com/

The API offers support for both JSON and binary responses. In the case where the selected value corresponds to an internal URL (e.g. https://beta.wallboard.info/api/storage/datasources/f56b7b4b780a46199754aedc74354703/resources/f56b7b4b780a46199754aedc74354703.jpg), the API will return the actual file associated with that URL.

path Parameters
datasourceId
required
string

ID of the datasource

query Parameters
path
string
Default: "$"
Example: path=$.charts[0]

JSON path to the resource

type
string
Default: "json"
Enum: "file" "json"

Datasource response type

Responses

Request samples

curl --location -g --request GET 'example.com/public-api/datasource/8994b2113f8e4496aacaa05a6b25073a/resource?path=$.charts[0].image&type=file'

Response samples

Content type

webhook

Call webhook as GET request

Every webhook can be called as GET request. The payload is a Base64 encoded JSON.

Webhook calls are async in a way that they always send back the response instantly, but the actual action executed in the background.

query Parameters
apiKey
string <JWT>
payload
string <Base64 encoded JSON>
Example: payload=eyJldmVudF9pZCI6ImRlY3JlYXNlIiwia2V5U2VsZWN0b3IiOiJ0ZXN0In0=

Original JSON in the example: {"event_id":"decrease","keySelector":"test"}

Responses

Request samples

curl -X GET \
  'https://example.com/public-api/integration/webhooks?apiKey=your_api_key&payload=eyJldmVudF9pZCI6ImRlY3JlYXNlIiwia2V5U2VsZWN0b3IiOiJ0ZXN0In0='         

Response samples

Content type
application/json
{
  • "message": "string"
}

Call webhook as POST request

Authorizations:
api_key_auth
Request Body schema: application/json
required

Custom JSON payload. The only required attribute is the event_id.

Example body: {"event_id":"decrease","keySelector":"test"}

Webhook calls are async in a way that they always send back the response instantly, but the actual action executed in the background.

event_id
string

Responses

Request samples

Content type
application/json
{
  • "event_id": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

customer

Get Customers

This endpoint is used to retrieve customer data.

query Parameters
search
string (search)

WBQL search expression

page
integer (page)
Default: 0

Page index

size
integer (size)
Default: 20

Size of page

sort
string (sort)

Sort expression

select
string (select)

WBQL select expression

Responses

Request samples

curl -X GET \
  '{{server_root}}/api/customer/?page=0&size=10'

Response samples

Content type
application/json
{
  • "id": 0,
  • "comment": "string",
  • "country": "string",
  • "expirationDate": "string",
  • "freeLicenses": 0,
  • "browserSessionLicenses": 0,
  • "deviceSessionLimit": 0,
  • "licenseType": "BASIC",
  • "profile": "BASIC",
  • "location": "string",
  • "name": "string",
  • "restricted": true,
  • "type": "string",
  • "contentDesignerEmail": "string",
  • "supportEmail": "string",
  • "createdDate": "string",
  • "needsToBeInvoiced": true,
  • "storageSize": 0,
  • "vertical": "BANKING_AND_FINANCE",
  • "ownerSubresellerId": 0,
  • "hiddenUIElementRule": "string",
  • "slaveId": "string",
  • "enableAutomaticDistributionToDms": true,
  • "userFullAccessIfNotInTeam": true,
  • "accessResourcesWithoutTeam": true,
  • "isDeviceAndGroupCreationEnabledInRootForTeamUsers": true,
  • "isContentAndGroupCreationEnabledInRootForTeamUsers": true,
  • "isFileAndFolderCreationEnabledInRootForTeamUsers": true,
  • "brandingGuideline": {
    },
  • "activeLicenses": 0,
  • "totalUserLoginCount": 0,
  • "totalUserPresenceTime": 0,
  • "lastActivity": "string",
  • "lastDeviceActivity": "string",
  • "totalLicenses": 0,
  • "subreseller": {
    },
  • "owner": {
    }
}