Updating Consent

Update the consent for the location of IoT Devices API (Asynchronous Request):

POST /devicelocations/actions/consents

Updates the consent for a device on the account. This request returns a synchronous transaction ID and the updated consent information, at device and account level, for each device (returned asynchronously) as a Device Location callback message. For precise location, confirm that the device being used has been certified to work. Your account manager or support contact can provide a list of certified devices.

Contents

Update the consent for the location of IoT devices (asynchronous): POST /devicelocations/action/consents

See also:
Register a Callback Listener
About Location Information
About Callback Services

Uses and Requirements

Who is allowed to give or update Consent

Consent for devices can only be given or updated by the account that owns those devices.

Update consent for Devices

For IoT devices, the device owner must give their consent for the device location information to determined and reported. When a location request is sent for an IoT device, ThingSpace checks to see if there is a current consent for your account to access the specified device’s location. If there isn’t a consent on file or consent is denied, ThingSpace will not proceed further to compute the location information of the device and a callback will be sent with an error. If the account owner gives consent (or if there is already a current consent), the location information will be returned in a callback message.

Update consent for Coarse or Precise Location

The account owner can update consent as allowed or denied for either Coarse or Precise location or both of them. Default is Coarse Location Only.

Back to Contents

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/loc/v1/devicelocations/action/consents

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token and must set the content-type to JSON.

Parameter Name

Data Type

Description

Authorization (required)

string

HTTP Authorization bearer token.

VZ-M2M-Token (required)

string

A valid session token returned by

POST/api/m2m/v1/session/login

Content-Type (required)

string

Must be application/json

Back to Contents

Request Body

Property Name

Data Type

Description

accountName (required)

string

The name of a billing account which is usually in the format of 10 digits, a hyphen and then five more digits. Any leading zeros must be included

deviceList (required)

array of device identifier objects

Each object in the array identifies a device that you want to enable location consent:

  • id: A device identifier value.
  • kind: The type of the identifier, IMEI, MEID, or ESN. Required for IoT devices
  • mdn: The 10-digit Mobile Directory Number (MDN) of the device. Required for all devices in the request (Remove the 1 from the beginning of an MSISDN to derive the MDN)
  • Consent: An integer representing the customer consent of the device. Default value is 2 (only coarse location allowed):
    • 0 - all location requests are allowed (including precise & coarse location)
    • 1 - only precise location allowed
    • 2 - only coarse location allowed
    • 3 - all location requests are denied (including precise & coarse location)

Example Request Body

Enabling Consent

{

  “deviceList”: [

    {“id”: “354677790348290”, “kind”: “imei”, “mdn”: “5557337468”,”consent”: “0”}

  ],

  “accountName”: “2234434445-32333”

}

Back to Contents

HTTP Response

Status 200
A successful response has, within the body of the response, a transaction ID that can be used to correlate the callbacks.

Parameter Name

Data Type

Description

transactionID

string

A unique string that associates the request with the location consent enable information that is sent in an asynchronous callback message. ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages will have the same transactionID

status

enum

QUEUED (all other values are reserved at this time)

Example Response, Status 200

{

    "transactionID": "e223cc6d-6ff7-4b6b-9f21-1dd7f474bd88",

    "status": "QUEUED"

}

Example Response, Status 400

All error messages are returned in this format:

{

    "errorCode": "INVALID_PARAMETER",

    "errorMessage": "UWS verification failure (Could not find account {account}.)"

}

Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.

Back to Contents

Consent Enabled Callback Parameters

Property Name

Data Type

Description

accountName (required)

string

The name (number) of the account that originated the device location request.

transactionID (required)

string

A unique string that associates the request with the location consent enable information that is sent in an asynchronous callback message. ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages will have the same transactionID

status (required)

string

SUCCESS or FAILED

deviceList (required)

array of device identifier objects

Each object in the array identifies a device that you want to enable location consent:

  • id: A device identifier value
  • kind: The type of the identifier, IMEI, MEID, or ESN.
  • mdn: The 10-digit Mobile Directory Number (MDN) of the device. Required for all devices in the request (Remove the 1 from the beginning of an MSISDN to derive the MDN)
  • Consent: An integer representing the customer consent of the device. Default value is 2 (only coarse location allowed)
    • 0 - all location requests are allowed (including precise & coarse location):
    • 1 - only precise location allowed
    • 2 - only coarse location allowed
    • 3 - all location requests are denied (including precise & coarse location)
  • errorResponse: Optional, only if there is an error. The response includes info, time and reportType

Note: deviceList can contain a maximum of 10000 devices

reportType (required)

string

A string representing the report the callback is reporting: CONSENT_RESPONSE, LOCATION_REPORT and STOP_PERIODIC_LOCATION_RESPONSE

Back to Contents

Example callback, SUCCESSS

{

    "accountName":"2234434445-32333",

    "deviceList":[

        {

            "consent":"1",

            "id":"354677790348290",

            "kind":"IMEI",

            "mdn":"5557337468"

        }

    ],

    "reportType":"CONSENT_RESPONSE",

    "status":"SUCCESS",

    "transactionID":"ee1e654d-8981-4cdc-962e-4f061f89e144"

}

Example callback, FAILED

{

   "accountName":"2234434445-32333",

   "deviceList":[

      {

         "error":{

            "info":"error from lwm2m server",

            "time":"20200731183948",

            "type":"INTERNAL ERROR"

         },

         "id":"354677790348290",

         "kind":"IMEI",

         "mdn":"5557337468"

      }

   ],

   "reportType":"CONSENT_RESPONSE",

   "status":"FAILED",

   "transactionID":"3df17f6c-4da9-4137-8476-498b948fd7dd"

}

 

Status 200
Success Response with no body.

Back to Contents

Updating Consent

Update the consent for an entire account or multiple devices (asynchronous):

PUT /devicelocations/action/consents

Update the consent for an entire account. This request returns a synchronous transaction ID and the updated consent information, at device and account level, for each device (returned asynchronously) as a Device Location callback message.

Contents

Update the consent for an entire account of multiple devices (asynchronous): PUT /devicelocations/action/consents

See also:
Register a Callback Listener
About Location Information
About Callback Services

Uses and Requirements

Who is allowed to give or update Consent

Consent for devices can only be given or updated by the account that owns those devices.

Update consent for a List of Devices (or Account)

For IoT devices, the device owner must give their consent for the device location information to be determined and reported. When a location request is sent for an IoT device, ThingSpace checks to see if there is a current consent for your account to access the specified device’s location. If there isn’t a consent on file or consent is denied, ThingSpace will not proceed further to compute the location information of the device and a callback will be sent with an error. If the account owner gives consent (or if there is already a current consent), the location information will be returned in a callback message.

Update consent for Coarse or Precise Location

The account owner can update consent as allowed or denied for either Coarse or Precise location or both of them. Default is Coarse Location.

Back to Contents

Request Components

HTTP Request

PUT https://thingspace.verizon.com/api/loc/v1/devicelocations/action/consents

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token and must set the content-type to JSON.

Parameter Name

Data Type

Description

Authorization (required)

string

HTTP Authorization bearer token.

VZ-M2M-Token (required)

string

A valid session token returned by

POST/api/m2m/v1/session/login.

Content-Type (required)

string

Must be application/json

Back to Contents

Request Body

Property Name

Data Type

Description

accountName (required)

string

The name of a billing account which is usually in the format of 10 digits, a hyphen and then five more digits. Any leading zeros must be included

allDeviceConsent (required)

string

This represents the location request’s consent at the account level. Default is set to 2 (only coarse location allowed):

  • 0 - all location requests are allowed (including precise & coarse location)
  • 1 - only precise location allowed
  • 2 - only coarse location allowed
  • 3 - all location requests are denied (including precise & coarse location)

Example Request Body

Enable Consent

{

  "accountName": "2234434445-32333",

  "allDeviceConsent": "0"

}

Back to Contents

HTTP Response

Status 200
A successful response has, within the body of the response, a transaction ID that can be used to correlate the callbacks.

Parameter Name

Data Type

Description

transactionID

string

A unique string that associates the request with the location consent enable information that is sent in an asynchronous callback message. ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages will have the same transactionID

status

enum

QUEUED (all other values are reserved at this time)

Back to Contents

Example Response, Status 200

{

    "transactionID": "ff8b157a-3843-499f-aefb-c5f70a358597",

    "status": "QUEUED"

}

Example Response, Status 400

All error messages are returned in this format:

{

    "errorCode": "INVALID_PARAMETER",

    "errorMessage": "Invalid JSON"

}

Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.

Back to Contents

consentEnableReport Callback Parameters

Property Name

Data Type

Description

accountName (required)

string

The name (number) of the account that originated the device location request.

transactionID (required)

string

A unique string that associates the request with the location consent enable information that is sent in an asynchronous callback message. ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages will have the same transactionID

status (required)

string

SUCCESS or FAILED

deviceList (required)

array of device identifier objects

Each object in the array identifies a device that you want to enable location consent:

  • id: A device identifier value
  • kind: The type of the identifier, IMEI, MEID, or ESN.
  • mdn: The 10-digit Mobile Directory Number (MDN) of the device. Required for all devices in the request.(Remove the 1 from the beginning of an MSISDN to derive the MDN)
  • Consent: An integer representing the customer consent of the device. Default value is 2 (only coarse location allowed):
    • 0 - all location requests are allowed (including precise & coarse location)
    • 1 - only precise location allowed
    • 2 - only coarse location allowed
    • 3 - all location requests are denied (including precise & coarse location)
  • errorResponse: Optional, only if there is an error: includes info and reportType

Note: deviceList can contain a maximum of 10000 devices for Coarse Location

Note: deviceList contains one device per callback for Precise Location

reportType (required)

string

A string representing the report the callback is reporting: CONSENT_RESPONSE, LOCATION_REPORT and STOP_PERIODIC_LOCATION_RESPONSE

allDeviceConsent (optional)

string

This represents the location request’s consent at the account level. Default set to 2 (only coarse location allowed):

  • 0 - all location requests are allowed (including precise & coarse location)
  • 1 - only precise location allowed
  • 2 - only coarse location allowed
  • 3 - all location requests are denied (including precise & coarse location)

Back to Contents

Example callback, SUCCESSS

{

   "accountName":"2234434445-32333",

   "appName":"DeviceLocation",

   "addressScheme":"rest",

   "message":{

      "accountName":"2234434445-32333",

      "transactionID":"c4feeffa-7481-41ad-8cb1-58976ba1ebe0",

      "reportType":"CONSENT_RESPONSE",

      "status":"SUCCESS",

      "allDeviceConsent":"0",

      "deviceList":[

         {

            "id":"354677790348290",

            "kind":"IMEI",

            "mdn":"5557337468",

            "consent":"0"

         }

      ]

   }

}

Example callback, FAILED

{

   "accountName":"2234434445-32333",

   "deviceList":[

      {

     

         "consent":"2",

         "error":{

            "info":"Error returned from LWM2M server",

            "type":"INTERNAL ERROR"

         },

         "id":"354677790348290",

         "kind":"IMEI",

         "mdn":"5557337468"

      }

   ],

   "reportType":"CONSENT_RESPONSE",

   "status":"FAILED",

   "transactionID":"8ee6b3b4-eb29-4406-98c7-9da54deea199"

}

 

Status 200
Success Response with no body.

Back to Contents

Updating Consent

Get the consent settings for the entire account or device list in an account (asynchronous):

GET /devicelocations/action/consents

Obtain the consent for an entire account or device list (maximum 100 IDs per request) in an account. This request returns the consent information, at device and account level, for each device in a synchronous response.

Contents

Get the consent for the entire account or device list in an account (asynchronous): GET /devicelocations/action/consents

See also:
Register a Callback Listener
About Location Information

Uses and Requirements

Who is allowed to Get the Consent Settings

The Consent Settings for IoT devices can only be retrieved (or gotten) by the account that owns those devices.

Get consent for all of the account or list of devices in an account

For IoT devices, the device owner must give their consent for the device location information to be determined and reported. When a location request is sent for an IoT device, ThingSpace checks to see if there is a current consent for your account to access the specified device’s location. If there isn’t a consent on file or consent is denied, ThingSpace will not proceed further to compute the location information of the device and a callback will be sent with an error. If the account owner gives consent (or if there is already a current consent), the location information will be returned in a callback message.

Request Components

HTTP Request

GET https://thingspace.verizon.com/api/loc/v1/devicelocations/action/consents?{accountName}&{deviceid}&{deviceid}

HTTP Request Example

GET 'https:// thingspace.verizon.com/api/loc/v1/devicelocations/action/consents?accountName=1123334445-32345&deviceid=354657770354181&deviceid=354657770354942'

Back to Contents

Path Parameters

Parameter Name

Data Type

Description

accountName (required)

string

The name of a billing account which is usually in the format of 10 digits, a hyphen and then five more digits. Any leading zeros must be included

deviceid (required)

array of strings

A list of device ids (IMEI)

Note: Maximum of 100 device IDs

Back to Contents

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token and must set the content-type to JSON.

Parameter Name

Data Type

Description

Authorization (required)

string

HTTP Authorization bearer token.

VZ-M2M-Token (required)

string

A valid session token returned by

POST/api/m2m/v1/session/login.

Content-Type (required)

string

Must be application/json

Back to Contents

Request Body

Parameter Name

Data Type

Description

accountName (required)

string

The name of a billing account which is usually in the format of 10 digits, a hyphen and then five more digits. Any leading zeros must be included

deviceList (required)

array of device identifier objects

Each object in the array identifies a device that you want to enable location consent:

  • id: A device identifier value
  • kind: The type of the identifier, IMEI, MEID, or ESN
  • mdn: The 10-digit Mobile Directory Number (MDN) of the device. Required for all devices in the request.(Remove the 1 from the beginning of an MSISDN to derive the MDN)
  • Consent: An integer representing the customer consent of the device. Default value is 2 (only coarse location allowed):
    • 0 - all location requests are allowed (including precise & coarse location)
    • 1 - only precise location allowed
    • 2 - only coarse location allowed
    • 3 - all location requests are denied (including precise & coarse location)

Note: deviceList can contain a maximum of 10000 devices

allDeviceConsent (optional)

string

This represents the location request’s consent at the account level:

  • 0 - all location requests are allowed (including precise & coarse location)
  • 1 - only precise location allowed
  • 2 - only coarse location allowed
  • 3 - all location requests are denied (including precise & coarse location)

Back to Contents

HTTP Response

Example Response, Status 200

{

    "deviceList": [

        {

            "id": "354658090354181",

            "kind": "IMEI",

            "mdn": "5883826163",

            "consent": "1"

        },

        {

            "id": "354658090355337",

            "kind": "IMEI",

            "mdn": "5883826191",

            "consent": "1"

        }

    ],

    "accountName": "2234434445-32333",

    "allDeviceConsent": "1"

}

Example Response, Status 400
All error messages are returned in this format:

{

    "errorCode": "INVALID_PARAMETER",

    "errorMessage": "Invalid account name"

}

Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.

Back to Contents

How it Works

Here are some use cases based on the account level consent settings:

Case 1:
  • If the customer wants to enable Precise and Coarse for an account (0) for entire account he sends the PUT API (above) for that
  • Then, if the customer wants to disable Precise location (2 – Coarse only) for a set of devices (more than 10,000 devices is not allowed), then they send the POST API with that level of consent set in device list
  • Result: the all device consent is set to allowed (0); only the set defined will be disabled for Precise Location; Coarse is still allowed for the set defined
Case 2:
  • If the customer wants to enable Precise location only (1 – means no Coarse, Precise only) for a set of devices only (more than 10,000 devices is not allowed), then they send the POST API with that consent set in a device list.
  • Result: All the device consent is still set to denied (3); only above set will be allowed for Precise Location only; Coarse is not allowed for these. Coarse can be allowed for the rest of the devices but that will require another use of the POST API.
Case 3:
  • If the customer wants to enable Precise and Coarse location (0) for a set of devices only (more than 10,000 devices is not allowed), then they send a POST API with that consent set in the device list
  • Result: All device consent is still set to allowed for Coarse (2); only the defined set will be allowed for Precise and Coarse Location

Back to Contents

Update Consent