API Reference

Change Device Cost Center

Uses and Requirements

ThingSpace sends an asynchronous CarrierService callback message for each device in the request when the device 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/costCenter

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

The request body identifies the devices to change and also the type of change you want to make.

Select the devices to change:

Parameter Name	Data Type	Description
devices (optional)	array of deviceIds objects	A list of the devices that you want to change, specified by device identifier. Do not include accountName, groupName, customFields, or servicePlan if you use this parameter.
kind, id (required) for `devices`	string	The type and value of the device identifier. ESN - decimal, 11 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 16 digits MDN - decimal, 10 digits MEID - hexadecimal, 14 characters MSISDN - decimal, 11 digits
accountName (optional) Recommended	string	The name of a billing account. This parameter is only required if the UWS account used for the current API session has access to multiple billing accounts. 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.
groupName (optional)	string	The name of a device group, if you want to only include devices in that group.
servicePlan (optional)	string	The name of a service plan, if you want to only include devices that have that service plan.
customFields (optional)	list of customField objects	Custom field names and values, if you want to only include devices that have matching values.
key (required) for `customFields`	string	The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
value (required) for `customFields`	string	The value of the custom field. The value is not case-sensitive, but other than that it must match exactly with the value set for a device. Wildcards and partial matches are not supported.

You can either specify up to 10,000 individual devices with the devices parameter, or you can use any combination of groupName, servicePlan, and customFields to run the request on all devices that match all criteria.

Change or remove the cost center code:

Parameter Name	Data Type	Description
filter	object	The filter criteria for cost centers to be removed or changed.
customFields (required)	array	Custom field keys and values to only include devices that have matching values.
costCenter (optional)	string	The new cost center code. Valid values are any string of up to 36 alphanumeric characters, space, dash, exclamation point, and pound sign.
removeCostCenter (optional)	Boolean	Set to true to remove the cost center code value. This flag takes precedence over a new costCenter value. If this flag is true and costCenter has a value, the cost center code is removed. Do not include this parameter, or set it to false to change the costCenter value.
accountName (optional)	string	The name of a billing account. An account name is usually numeric, and must include any leading zeros.
servicePlan (optional)	string	The name of a service plan that is being changed to. If removing service plans, this value is ignored.

Change the customer name and/or address:

Parameter Name	Data Type	Description
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.
customerName required for primaryPlaceOfUse	object	The customer name to be used for line usage taxation.
title (optional)	string	An optional title for the customer, such as “Mr.” or “Dr.”
firstName required for customerName	string	The customer’s first name. Valid values are any string of up to 20 alphanumeric characters, space, dash, exclamation point, and pound sign.
middleName (optional)	string	The customer’s middle name.
lastName required for customerName	string	The customer’s last name. Valid values are any string of up to 25 alphanumeric characters, space, dash, exclamation point, and pound sign.
suffix (optional)	string	An optional suffix for the customer name, such as “Jr.” or “III.”
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.
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.
country required for address	string	Either “US” or “USA” for the country of the line’s primary place of use.
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
emailAddress (optional)	string	An email address for the customer.

Example Request Body

Change the cost center code for a single device

{
    "costCenter": "cc12345",
    "devices": [
    {
        "deviceIds": [
        {
            "id": "20-digit ICCID",
            "kind": "iccid"
        }
        ]
    }
    ]
}

Change the cost center code for multiple devices

{
    "costCenter": "cc12345",
    "devices": [
    {
        "deviceIds": [
        {
            "id": "20-digit ICCID",
            "kind": "iccid"
        }
        ]
    },
    {
        "deviceIds": [
        {
            "id": "20-digit ICCID",
            "kind": "iccid"
        }
        ]
    }
    ]
}

Remove the cost center code from all devices in an account that have a specified custom field value

{
   "filter":{
      "customFields":[
         {
            "key":"string",
            "value":"string"
         }
      ]
   },
   "costCenter":"string",
   "removeCostCenter":true,
   "accountName":"string",
   "servicePlan":"string"
}

Change the name and address for a device

{
    "devices":[
    {
        "deviceIds":[
        {
            "kind":"imei",
            "id":"15-digit IMEI"
        }
        ]
    }
    ],
    "accountName": "0000123456-00001",
    "primaryPlaceOfUse":{
    "customerName":{
        "title":"President",
        "firstName":"Zaffod",
        "lastName":"Beeblebrox"
    },
    "address":{
        "addressLine1":"1600 Pennsylvania Ave NW",
        "city":"Washington",
        "state":"DC",
        "zip":"20500",
        "country":"USA"
    }
    }
}

Success Responses

Status 200

Parameter Name	Data Type	Description
requestId	string	A unique string 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 of the callback messages have the same requestId.

Example Success Response

{
    "requestId": "595f5c44-eeee-ffff-gggg-020a1545a84d"
}

Example Success Callback Response

Callback for changing a cost center

{
    "username":"",
    "password":"",
    "requestId":"c8de7c1d-eeee-ffff-gggg-db76cb2ce509",
    "deviceIds":[  
    {  
        "id":"10-digit phone number",
        "kind":"mdn"
    }
    ],
    "deviceResponse":{
    "deviceCostCenterResponse": {
        "costCenterCode": "VZW103"
    }
    }
}

Callback for removing a cost center

{
    "username":"user name",
    "password":"user's password",
    "requestId":"c8de7c1d-eeee-ffff-gggg-db76cb2ce509",
    "deviceIds":[  
    {  
        "id":"10-digit phone number",
        "kind":"mdn"
    }
    ],
    "deviceResponse":{
    "deviceCostCenterResponse": {}
    }
}

Callback for changing Primary Place of Use

{
      "username": "",
      "password": "",
      "requestId": "c8de7c1d-eeee-ffff-gggg-db76cb2ce509",
      "deviceIds": [
        {
          "id": "15-digit IMEI",
          "kind": "imei"
        }
      ],
      "deviceResponse": {
        "deviceCostCenterResponse": {
          "primaryPlaceOfUse": {
            "address": {
              "addressLine1": "9808",
              "addressLine2": "Scranton Road",
              "city": "San Diego",
              "state": "CA",
              "country": "US",
              "zip": "92121",
              "zip4": "01234",
              "phone": "1234567890",
              "phoneType": "M",
              "emailAddress": "zaffod@theinternet.com"
            },
            "customerName": {
              "firstName": "Zaffod",
              "lastName": "Beeblebrox",
              "middleName": "Q",
              "title": "President",
              "suffix": "I"
            }
          }
        }
      },
      "callbackCount": 1,
      "maxCallbackThreshold": 4
    }

Change Device Cost CenterCopy Anchor Link

Uses and RequirementsCopy Anchor Link

Request ComponentsCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Example Request BodyCopy Anchor Link

Success ResponsesCopy Anchor Link

Example Success ResponseCopy Anchor Link

On this page