Change Device Contact Information:

PUT /devices/actions/contactInfo

Changes the name and address associated with devices.  Note: For 5G Business Internet-enabled lines, this API will perform a 5G Business Internet Address Qualification at the new address before completing the change. Monitor the CarrierService callback for completion status.

Contents

See Also
Activate Devices
Get Device Information
Change Device Cost Center

Uses and Requirements

The existing Primary Place of Use values set for the devices are erased by this request and are replaced by the new values specified in the request. If you do not provide a value for a parameter, it is set to an empty string.

The M2M Platform sends a CarrierService callback message when the device contact information has been changed, or if there was a problem and the change could not be completed.

Request Components

HTTP Request

PUT https://thingspace.verizon.com/api/m2m/v1/devices/actions/contactInfo

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 /session/login.
Content-Type
required
string Must be application/json.

Request Body

Select the devices to change:

Parameter Name Data Type Description
accountName
optional
*Recommended
string The name of the billing account that the devices belong to. An account name is usually numeric, and must include any leading zeros.

*By coding for the account number today, you prevent future code from breaking if you ever add a new sub-account.

devices
optional*
array of deviceIds objects A list of the devices that you want to change, specified by device identifier. You only need to provide one identifier per device. Do not include accountName, groupName, customFields, or servicePlan if you use this parameter.
id,
kind
required for devices
string The type and value of the device identifier.
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 16 digits
  • MDN - decimal, 10 digits
  • MSISDN - decimal, 11 digits
   ipAddress
   optional
string An IPv4 IP address in the format 1-255.0-255.0-255.0-255.
primaryPlaceOfUse
required
object The customer name and the address of the device’s primary place of use. These values are applied to all devices in the request.
The Primary Place of Use location may affect taxation or have other legal implications. You may want to speak with legal and/or financial advisers before entering values for these fields.
address
required for primaryPlaceOfUse
object The customer address for the line’s primary place of use, for line usage taxation.
addressLine1
required for address
string The street address for the line’s primary place of use. This must be a physical address for taxation; it cannot be a P.O. box.
addressLine2
optional
string Optional additional street address information.
city
required for address
string The city for the line’s primary place of use.
country
required for address
string Either “US” or “USA” for the country of the line’s primary place of use.
emailAddress
optional
string An email address for the customer.
phone
optional
string A phone number where the customer can be reached.
phoneType
optional
string A single letter to indicate the customer phone type:
  • M = Mobile
  • H = Home
  • F = Fax
  • W = Work/Business
  • P = Pager
state
required for address
string The state for the line’s primary place of use.
zip
required for address
string The ZIP code for the line’s primary place of use.
zip4
optional
string The ZIP+4 for the line’s primary place of use.
customerName
required for primaryPlaceOfUse
object The customer name to be used for line usage taxation.
firstName
required for customerName
string The customer’s first name.
middleName
optional
string The customer’s middle name.
lastName
required for customerName
string The customer’s last name.
suffix
optional
string An optional suffix for the customer name, such as “Jr.” or “III.”
title
optional
string An optional title for the customer, such as “Mr.” or “Dr.”
deviceListWithServiceAddress
only used for Business Internet/ Fixed Wireless access
array An object that associates a device with a primary place of use.
    devices
    required
array of deviceIds objects A list of the devices that you want to change, specified by device identifier. You only need to provide one identifier per device. Do not include accountName, groupName, customFields, or servicePlan if you use this parameter.
    id
    kind,
    required
string The type and value of the device identifier.
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 16 digits
  • MDN - decimal, 10 digits
  • MSISDN - decimal, 11 digits
primaryPlaceOfUse
required
object The customer name and the address of the device’s primary place of use. These values are applied to all devices in the request.
The Primary Place of Use location may affect taxation or have other legal implications. You may want to speak with legal and/or financial advisers before entering values for these fields.
address
required 
object The customer address for the line’s primary place of use, for line usage taxation.
addressLine1
required
string The street address for the line’s primary place of use. This must be a physical address for taxation; it cannot be a P.O. box.
addressLine2
optional
string Optional additional street address information.
city
required
string The city for the line’s primary place of use.
country
required
string Either “US” or “USA” for the country of the line’s primary place of use.
emailAddress
optional
string An email address for the customer.
phone
optional
string A phone number where the customer can be reached.
phoneType
optional
string A single letter to indicate the customer phone type:
  • M = Mobile
  • H = Home
  • F = Fax
  • W = Work/Business
  • P = Pager
state
required
string The state for the line’s primary place of use.
zip
required
string The ZIP code for the line’s primary place of use.
zip4
optional
string The ZIP+4 for the line’s primary place of use.
customerName
required
object The customer name to be used for line usage taxation.
firstName
required
string The customer’s first name.
middleName
optional
string The customer’s middle name.
lastName
required
string The customer’s last name.
suffix
optional
string An optional suffix for the customer name, such as “Jr.” or “III.”
title
optional
string An optional title for the customer, such as “Mr.” or “Dr.”
ipAddress
optional
string An IPv4 IP address in the format 1-255.0-255.0-255.0-255.

Example Request Body

Change the contact information for a device. Note: deviceListWithServiceAddress is only relevant for Business Internet/Fixed Wireless Access. 

{
  "accountName": "0000123456-00001",
  "devices": [
    {
      "deviceIds": [
        {
          "id": "20-digit ICCID",
          "kind": "iccid"
        }
      ],
      "ipAddress": "10.0.0.1"
    }
  ],
  "primaryPlaceofUse": {
    "address": {
      "addressLine1": "1600 Pennsylvania Ave NW",
      "city": "Wasington",
      "country": "USA",
      "emailAddress": "zaffod@president.gov",
      "phone": "10-digit phone number",
      "phoneType": "W",
      "state": "DC",
      "zip": 20500
    },
    "customerName": {
      "firstName": "Zaphod",
      "lastName": "Beeblebrox",
      "title": "President"
    }
  },
  "deviceListWithServiceAddress": [
    {
      "deviceIds": [
        {
          "id": "20-digit ICCID",
          "kind": "iccid"
        }
      ],
      "primaryPlaceofUse": {
        "address": {
          "addressLine1": "1600 Pennsylvania Ave NW",
          "city": "Wasington",
          "country": "USA",
          "emailAddress": "zaffod@president.gov",
          "phone": "10-digit phone number",
          "phoneType": "W",
          "state": "DC",
          "zip": 20500
        },
        "customerName": {
          "firstName": "Zaphod",
          "lastName": "Beeblebrox",
          "title": "President"
        }
      },
      "ipAddress": "10.0.0.1"
    }
  ]
}

Success Responses

Status 200

Parameter Name Data Type Description
requestId string A unique string (32-bit UUID) that associates the request with the results that are sent via a callback service.
The ThingSpace Platform sends a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All callback messages have a requestId.

Example Success Response

{
  "requestId": "24da9f9a-d110-4a54-86b4-93fb76aab83c"
}

Example Callback Response

The callback type is "CarrierService".

{
  "requestId": "24da9f9a-d110-4a54-86b4-93fb76aab83c",
  "deviceIds": [
    {
      "id": "10-digit phone number",
      "kind": "mdn"
    }
  ],
  "faultResponse": {
    "faultcode": "UnifiedWebService.REQUEST_FAILED.CarrierRequestUnsuccessful",
    "faultstring": "REQUEST_FAILED. Address is not 5GBI Eligible"
  },
  "status": "Failed",
  "callbackCount": 1,
  "maxCallbackThreshold": 4
}

Failure Responses

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

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

Try It Out!