Updating Consent
Update the Consent for All Devices on an Account (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. Consent for devices can only be given or updated by the account that owns those devices. 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 the 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. The account owner can update consent as allowed or denied for either Coarse or Precise location or both of them. Default is Coarse Location.
Header Parameters
The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization (required) | string | HTTP Authorization bearer token: Authorization: Bearer {token} |
| VZ-M2M-Token (required) | string | A valid session token: VZ-M2M-Token: {M2Mtoken} |
| Content-Type (required) | string | Must be application/json Content-Type: application/json |
HTTP Request
PUT https://thingspace.verizon.com/api/loc/v1/devicelocations/action/consents
Request Parameters
| Property Name | Data Type | Description |
|---|---|---|
| accountName (required) | string | The numeric name of a billing account. 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). Valid values are: 0 - all location requests are allowed (including precise & coarse location), 1 - only precise location allowed, 2 - only coarse location allowed or 3 - all location requests are denied (including precise & coarse location). |
Request Body
Example Request Body to Enable Consent
{
"accountName": "0000123456-00001",
"allDeviceConsent": "0"
}Success Response
Status 200
A successful response has a transactionId that can be used to correlate the callbacks.
Example Response:
{
"transactionID": "ff8b157a-eeee-ffff-gggg-c5f70a358597",
"status": "QUEUED"
}Success Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| transactionID | string | A unique string (UUID) 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 | string | The status of the request. This will show QUEUED for successful requests. |
Failure Responses
All error messages are returned in this format:
{
"errorCode": "The 3-digit HTML error code",
"errorMessage": "string"
}Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.
Callback Response
These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit About Callback Services. The callback to subscribe to is consentEnableReport Example callback, SUCCESSS:
{
"accountName":"0000123456-00001",
"appName":"DeviceLocation",
"addressScheme":"rest",
"message":{
"accountName":"0000123456-00001",
"transactionID":"ff8b157a-eeee-ffff-gggg-c5f70a358597",
"reportType":"CONSENT_RESPONSE",
"status":"SUCCESS",
"allDeviceConsent":"0",
"deviceList":[
{
"id":"900000000000009",
"kind":"IMEI",
"mdn":"10-digit phone number",
"consent":"0"
}
]
}
}Example callback, FAILED:
{
"accountName":"0000123456-00001",
"deviceList":[
{
"consent":"2",
"error":{
"info":"Error returned from LWM2M server",
"type":"INTERNAL ERROR"
},
"id":"900000000000009",
"kind":"IMEI",
"mdn":"10-digit phone number"
}
],
"reportType":"CONSENT_RESPONSE",
"status":"FAILED",
"transactionID":"ff8b157a-eeee-ffff-gggg-c5f70a358597"
}Callback Parameters
| Property Name | Data Type | Description |
|---|---|---|
| accountName | string | The numeric name of the account that originated the device location request. |
| transactionID | string | A unique string (UUID) 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. |
| reportType | string | A string representing the report the callback is reporting. This can be: CONSENT_RESPONSE, LOCATION_REPORT and STOP_PERIODIC_LOCATION_RESPONSE. |
| status | string | If data is returned, the status will show SUCCESS. If data is not returned, status will show FAILED. |
| allDeviceConsent | string | This represents the location request’s consent at the account level. Default set to 2 - only coarse location allowed. This can be: 0 - all location requests are allowed (including precise & coarse location), 1 - only precise location allowed, 2 - only coarse location allowed and 3 - all location requests are denied (including precise & coarse location). |
| deviceList | array | Each object in the array identifies a device to enable location consent and will have id, kind, mdn and a flag for consent. Note: deviceList can contain a maximum of 10,000 devices for Coarse Location Note: deviceList contains one device per callback for Precise Location |
| id | string | A device identifier value. |
| kind | string | The type of the identifier. |
| mdn | string | The 10-digit Mobile Directory Number (phone number) of the device. |
| Consent | integer | A flag representing the customer consent of the device. Default value is 2 - only coarse location allowed. Valid values are: 0 - all location requests are allowed (including precise & coarse location), 1 - only precise location allowed, 2 - only coarse location allowed and 3 - all location requests are denied (including precise & coarse location). |
| error | object | If a callback shows as failed, there will be an info and type in this object. If there is no error, this object will not be displayed. |
| info | string | A description of the type of error. |
| type | string | The type of error that occurred. |