---
title: B-Deploy Device Endpoints (v2)
slug: develop/b-deploy-device-endpoints-v2
docTags: 
createdAt: 2025-03-11T07:03:28.938Z
---

These endpoints allow users to automatically provision BrightSign players over the internet. This endpoint handles everything regarding *individual* players if you add your serial number to BrightSign’s cloud storage with an associated player name, provisioning package name, and the URL where the provisioning package is hosted. The URL is optional - it can be left blank if using a setup package.

Base URL for these endpoints:  ***https\://provision.bsn.cloud/rest-device/v2/device/***

***

# GET 

Retrieves a collection of provision records which belong to your network in B-Deploy

**URL Parameters**

- `query[NetworkName]` <font color="#704ae0">string</font> <font color="#01a0af">required</font>: The BSN.Cloud/BSN.com network name
- `sort[serial]` <font color="#704ae0">byte</font> <font color="#01a0af">optional</font>: A flag which defines whether the returned list should be sorted by player serial
- `page[pageNum]` <font color="#704ae0">number</font> <font color="#01a0af">optional</font>: An index of a page in the paged list to retrieve
- `page[pageSize]` <font color="#704ae0">number</font> <font color="#01a0af">optional</font>: The maximum number of provision records on a page in the paged list

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Request** **Example**

- `query[NetworkName]` is set to `JaneDoeNetwork`
- `sort[serial]` is set to `1`
- `page[pageNum]` is set to `1`
- `page[pageSize]` is set to `20`

```text
GET /rest-device/v2/device/?query%5BNetworkName%5D=JaneDoeNetwork&sort%5Bserial%5D=1&page%5BpageNum%5D=1&page%5BpageSize%5D=20 HTTP/1.1
Host: provision.bsn.cloud
Connection: Keep-Alive
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
```

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Success Response Body**

<font color="#089a4d">200</font>: Returns a paged list of [Provision Record Entity  (v2)](docId\:OS9Y0aZ6JykvQYbB9vujv)&#x20;

**Response Example**

```json
{
   "error": null,
   "result":    {
      "total": 1,
      "matched": 1,
      "players":       [
                  {
            "_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
            "client": "baconnected",
            "NetworkName": "JaneDoeNetwork",
            "username": "JaneDoe@brightsign.biz",
            "serial": "123456789012",
            "name": "My Player",
            "model": "XC4055",
            "desc": "Brand New Player",
            "setupName": "My Setup Package",
            "createdAt": "2024-08-25T13:38:00.042Z",
            "updatedAt": "2024-08-25T13:38:00.042Z",
            "__v": 0
         }
      ],
      "priv": "user"
   }
}
```

**Failure Response**

<font color="#9a0808">400</font>: The request is malformed and therefore invalid

<font color="#9a0808">401</font>: The access token is invalid or not specified

<font color="#9a0808">403</font>: The supplied access token, though valid, doesn't provide access to this method.

<font color="#9a0808">5XX</font>: Any 500 code is an internal server error

# GET  /?\_id=\{string}

Retrieves a provision record from B-Deploy which has the specified ID.

**Query String Parameter**

- `_id` <font color="#704ae0">string</font> <font color="#01a0af">required</font>: The unique identifier of the provision record to retrieve. If this parameter is not included in the URL, the GET request will return all provision records associated with the account

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Request** **Example**

- `_id` is set to `1a2b3c4d5e6f7a8b9c0d1e2f`

```none
GET /rest-device/v2/device/?_id=1a2b3c4d5e6f7a8b9c0d1e2f HTTP/1.1
Host: provision.bsn.cloud
Connection: Keep-Alive
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
```

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Success Response Body**

<font color="#0F766E">200</font>: Returns the specified [Provision Record Entity  (v2)](docId\:OS9Y0aZ6JykvQYbB9vujv)&#x20;

**Response Example**

```json
{
   "error": null,
   "result":    {
      "_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
      "client": "baconnected",
      "NetworkName": "JaneDoeNetwork",
      "username": "JaneDoe@brightsign.biz",
      "serial": "ABCD00000001",
      "name": "ProvisionTest",
      "model": "XC4055",
      "desc": "Brand New Player",
      "setupName": "My Setup Package",
      "createdAt": "2024-08-25T13:38:00.042Z",
      "updatedAt": "2024-08-25T13:38:00.042Z",
      "__v": 0
   }
}
```

**Failure Response**

<font color="#B91C1C">400</font>: The request is malformed and therefore invalid

<font color="#B91C1C">401</font>: The access token is invalid or not specified

<font color="#B91C1C">403</font>: The supplied access token, though valid, doesn't provide access to this method.

<font color="#B91C1C">404</font>: The server cannot find the requested resource (the path does not exist)

<font color="#B91C1C">5XX</font>: Any 500 code is an internal server error

# GET  /?serial=\{string}

Retrieves a provision record from B-Deploy created for a player having the specified serial.

**Query String Parameter**

- `serial` <font color="#704ae0">string </font><font color="#01a0af">required</font>: The serial of a player which is specified by a provision record. If this parameter is not included in the URL, the GET request will return all provision records associated with the account

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Request** **Example**

- `serial` is set to `ABCD00000001`

```none
GET /rest-device/v2/device/?serial=ABCD00000001 HTTP/1.1
Host: provision.bsn.cloud
Connection: Keep-Alive
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
```

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Success Response Body**

<font color="#0F766E">200</font>: Returns the specified [Provision Record Entity  (v2)](docId\:OS9Y0aZ6JykvQYbB9vujv)&#x20;

**Response Example**

```json
{
   "error": null,
   "result":    {
      "total": 1,
      "matched": 1,
      "players":       [
                  {
            "_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
            "client": "baconnected",
            "NetworkName": "JaneDoeNetwork",
            "username": "JaneDoe@brightsign.biz",
            "serial": "ABCD00000001",
            "name": "ProvisionTest",
            "model": "XC4055",
            "desc": "Brand New Player",
            "setupName": "My Setup Package",
            "createdAt": "2024-08-25T13:38:00.042Z",
            "updatedAt": "2024-08-25T13:38:00.042Z",
            "__v": 0
         }
      ],
      "priv": "user"
   }
}
```

**Failure Response**

<font color="#B91C1C">400</font>: The request is malformed and therefore invalid

<font color="#B91C1C">401</font>: The access token is invalid or not specified

<font color="#B91C1C">403</font>: The supplied access token, though valid, doesn't provide access to this method.

<font color="#B91C1C">5XX</font>: Any 500 code is an internal server error

# POST 

Creates a provision record for a specific player and refers to either a setup package stored in B-Deploy or provided by an external service.

**Request Body**

- `username` <font color="#704ae0">string </font><font color="#01a0af">required</font>: The login of the person who owns the record. Note that the person may or may not be registered in BSN.Cloud.
- `serial` <font color="#704ae0">string </font><font color="#01a0af">required</font>: The serial number of the player represented by the provision record
- `name` <font color="#704ae0">string </font><font color="#01a0af">optional</font>: The name that the target player will get as a result of provisioning. When specified, it overrides the values specified in the referenced setup package.
- `NetworkName` <font color="#704ae0">string </font><font color="#01a0af">required</font>: The name of the network to which the specified player should be provisioned
- `model` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: The model of the player which has the specified serial
- `desc` <font color="#704ae0">string </font><font color="#01a0af">optional</font>:  The description that the target player will get in result of provisioning. When specified, it overrides the values specified in the referenced setup package.
- `setupId` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: The unique identifier of the setup package stored in B-Deploy and managed using the PSS API documented in [B-Deploy Setup Endpoints (v2)](docId\:XgMcFQZr1PdBve-TQeQxB)&#x20;
- `setupName` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: The descriptive name of a setup package stored in B-Deploy and managed using the PSS API documented in [B-Deploy Setup Endpoints (v2)](docId\:XgMcFQZr1PdBve-TQeQxB)&#x20;
- `url` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: The URL from which the player will download its presentation as part of the final provisioning step
- `userdata` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: Allows you to allows you to provide additional attributes to a custom setup package

**Request** **Example**

```text
POST /rest-device/v2/device HTTP/1.1
Host: provision.bsn.cloud
Content-Type: application/json
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
Content-Type: application/json
Content-Length: 252
```

This is an example request body with a `setupId` and `setupName`:

```json
{
  "username": "JaneDoe@brightsign.biz",
  "serial": "ABCD00000001",
  "name": "ProvisionTest",
  "NetworkName": "Test",
  "model": "XC4055",
  "desc": "Jane's player",
  "setupId": "f2e1d0c9b8a7f6e5d4c3b2a1",
  "setupName": "My Setup Package",
  "userdata": ""
}
```

This is an example request body with a `url`:

```json
{
  "username": "JaneDoe@brightsign.biz",
  "serial": "ABCD00000001",
  "name": null,
  "NetworkName": "Test",
  "model": "XC4055",
  "desc": "Jane's player",
  "userdata": "key=value",
  "url": "https://provisiondemo.brightsignnetwork.com/autorun.zip"
}
```

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Success Response**

<font color="#089a4d">201</font>: Returns the unique identifier of a provision record created in B-Deploy and added to your network

**Failure Response**

<font color="#9a0808">400</font>: The request is malformed and therefore invalid

<font color="#9a0808">401</font>: The access token is invalid or not specified

<font color="#9a0808">403</font>: The supplied access token, though valid, doesn't provide access to this method 

<font color="#9a0808">415</font>: The server cannot accept the data representation that you sent (as specified in the header)

<font color="#9a0808">5XX</font>: Any 500 code is an internal server error

# PUT  /?\_id=\{string}

Modifies a provision record of a specified player in B-Deploy

**Request Body**

- `_id` <font color="#704ae0">string</font><font color="#01a0af"> required</font>: The unique identifier (a 24 digits-long hexadecimal number) of the device object
- `username` <font color="#704ae0">string </font><font color="#01a0af">required</font>: The login of the person who owns the record. Note that the person may or may not be registered in BSN.Cloud.
- `serial` <font color="#704ae0">string </font><font color="#01a0af">required</font>: The serial number of the player represented by the provision record&#x20;
- `name` <font color="#704ae0">string </font><font color="#01a0af">optional</font>: The name that the target player will get as a result of provisioning. When specified, it overrides the values specified in the referenced setup package.
- `NetworkName` <font color="#704ae0">string </font><font color="#01a0af">required</font>: The name of the network to which the specified player should be provisioned
- `model` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: The model of the player which has the specified `serial`
- `desc` <font color="#704ae0">string </font><font color="#01a0af">optional</font>: The description that the target player will get as a result of provisioning. When specified, it overrides the values specified in the referenced setup package.
- `setupId` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: The unique identifier of the setup package stored in B-Deploy and managed using the PSS API documented on [this page](docId\:XgMcFQZr1PdBve-TQeQxB).&#x20;
- `setupName` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: The descriptive name of a setup package stored in B-Deploy and managed using the PSS API documented on [this page](docId\:XgMcFQZr1PdBve-TQeQxB).
- `url` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: Refers to the setup package or handler provided by external services, like partner applications.
- `userdata` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: An optional property which allows you to provide additional attributes to a custom setup package

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Request** **Example**

This method requires an `url` property value with an absolute URL value format or a pair of `setupId` and `setupName` property values.

```text
PUT /rest-device/v2/device/ HTTP/1.1
Host: provision.bsn.cloud
Content-Type: application/json
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
Content-Type: application/json
Content-Length: 283
```

This is the `url` example request body:

```json
{
  "_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
  "username": "JaneDoe@brightsign.biz",
  "serial": "ABCD00000001",
  "name": "ProvisionTest",
  "NetworkName": "Test",
  "model": "XC4055",
  "desc": "Jane's player",
  "url": "https://www.janeplayers.com/setups/autorun.zip",
  "userdata": "key=value"
}
```

This is the `setupId` and `setupName` example request body:

```json
{
  "_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
  "username": "JaneDoe@brightsign.biz",
  "serial": "ABCD00000001",
  "name": "ProvisionTest",
  "NetworkName": "Test",
  "model": "XC4055",
  "desc": "Jane's player",
  "setupId": "f2e1d0c9b8a7f6e5d4c3b2a1",
  "setupName": "My Setup Package",
  "userdata": ""
}
```

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Success Response**

<font color="#089a4d">200</font>: The existing provision record properties have been updated.

**Failure Response**

<font color="#9a0808">400</font>: Either the request or request body is malformed and therefore invalid

<font color="#9a0808">401</font>: The access token is invalid or not specified

<font color="#9a0808">403</font>: The supplied access token, though valid, doesn't provide access to this method 

<font color="#9a0808">415</font>: The server cannot accept the data representation that you sent (as specified in the header)

<font color="#9a0808">5XX</font>: Any 500 code is an internal server error

# DELETE  /?\_id=\{string}

Removes a provision record having the specified ID in B-Deploy

**Query String Parameter**

- `_id` <font color="#704ae0">string</font> <font color="#01a0af">required</font>: The player database record identifier

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Request** **Example**

- `_id` is set to `1a2b3c4d5e6f7a8b9c0d1e2f`

```text
DELETE /rest-device/v2/device/?_id=1a2b3c4d5e6f7a8b9c0d1e2f HTTP/1.1
Host: provision.bsn.cloud
Content-Type: application/json
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
```

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Success Response**

<font color="#089a4d">200</font>: The specified provision record has been removed

**Failure Response**

<font color="#9a0808">400</font>: The request is malformed and therefore invalid

<font color="#9a0808">401</font>: The access token is invalid or not specified

<font color="#9a0808">403</font>: The supplied access token, though valid, doesn't provide access to this method 

<font color="#B91C1C">404</font>: A provision record with the specified ID does not exist

<font color="#9a0808">5XX</font>: Any 500 code is an internal server error



# DELETE  /?serial=\{string}

Removes a provision record related to a player having the specified serial number in B-Deploy

**Query String Parameter**

- `serial` <font color="#704ae0">string</font> <font color="#01a0af">required</font>: The player serial

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Request** **Example**

- `serial` is set to `ABCD00000001`

```text
DELETE /rest-device/v2/device/?serial=ABCD00000001 HTTP/1.1
Host: provision.bsn.cloud
Content-Type: application/json
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
```

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Success Response**

<font color="#089a4d">200</font>: The specified provision record has been removed

**Failure Response**

<font color="#9a0808">400</font>: The request is malformed and therefore invalid

<font color="#9a0808">401</font>: The access token is invalid or not specified

<font color="#9a0808">403</font>: The supplied access token, though valid, doesn't provide access to this method 

<font color="#B91C1C">404</font>: A provision record with the specified serial number does not exist

<font color="#9a0808">5XX</font>: Any 500 code is an internal server error



# DELETE  /ids/\{array}

Removes a collection of provision records having the specified identifiers in B-Deploy

**Segment**

`array` <font color="#704ae0">string[]</font>

An array of provision record identifiers

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Request** **Example**

- `array` is set to ` ["1a2b3c4d5e6f7a8b9c0d1e2f"]`

```text
DELETE /rest-device/v2/device/ids/["1a2b3c4d5e6f7a8b9c0d1e2f"] HTTP/1.1
Host: provision.bsn.cloud
Connection: Keep-Alive
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
```

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Success Response**

<font color="#089a4d">200</font>: The request is executed successfully and the indication of which records have been removed is in the response payload.&#x20;

**Response Example**

```json
{
   "error": null,
   "result":    {
      "deletedCount": 1,
      "deletedIds": ["1a2b3c4d5e6f7a8b9c0d1e2f"],
      "failedIds": [],
      "message": "All players were deleted successfully"
   }
}
```

**Failure Response**

<font color="#9a0808">400</font>: The request is malformed and therefore invalid

<font color="#9a0808">401</font>: The access token is invalid or not specified

<font color="#9a0808">403</font>: The supplied access token, though valid, doesn't provide access to this method 

<font color="#9a0808">5XX</font>: Any 500 code is an internal server error