GetDeviceInformation

Returns information about a specified device, including its provisioning state, service plan, MDN, and IP address.

Request Parameters

Parameter Type Description
Device
required
DeviceIdentifier

The device for which you want information, specified by device identifier.

NOTE: You can use GetDeviceList to get a list of all devices in the account.

Kind
required
string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN
Identifier
required
string The value of the device identifier.

Response Parameters

Parameter Type Description
Device DeviceInformation The list of information about the device.
AccountName string The billing account that the device is associated with.
CarrierInformation CarrierInformation The carrier information associated with the device.
CarrierName string The name of the carrier.
ServicePlan string

The service plan that the device is assigned to.

NOTE: Service plan changes made through other tools are synchronized with the M2M Platform once per day, so you may need to wait up to 24 hours before those changes are returned by the GetDeviceInformation API.

State string The current state of the device, which will be one of these values:
  • Pre-active
  • active
  • deactive
  • suspend
  • pending Cost Center Codes change
  • pending resume
  • pending MDN change
  • pending PRL Update
  • pending preactive
  • pending activation
  • pending deactivation
  • pending suspend
  • pending service plan change
  • pending ESN / MEID change
  • pending account update
DeviceGroupName string The device groups that the device belongs to.
DeviceIdentifiers list of DeviceIdentifier One or more identifiers for the device.
Kind string The type of the device identifier. Valid types of identifiers are:

  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
CreatedAt dateTime The date and time that the device was added to the system.
IPAddress string The IP address of the device.
LastActivationDate dateTime The date and time that the device was last activated.
LastActivationBy string The user who last activated the device.
BillingCycleEndDate dateTime The date that the device's current billing cycle ends.
Connected boolean True if the device is connected; false if it is not.
LastConnectionDate dateTime If the device is not connected, this indicates the last known connection date.
CustomFields CustomFieldObj The custom fields and values that have been set for the device.
Name string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Value string The value of the custom field.

Allowed characters in custom field values:

  • Alphanumeric characters
  • / (forward slash)
  • SPACE
  • @ (at sign)
  • . (period)
  • , (comma)
  • : (colon)
  • - (hyphen)
  • _ (underscore)
  • ( (open parenthesis)
  • ) (close parenthesis)
  • [ (open bracket)
  • ] (close bracket)
  • # (number sign or hash)
FeatureCodes FeatureCode The feature codes for the device. Feature codes are only available with the Verizon Wholesale network.
Code string
Description string
ExtendedAttributes ExtendedAttributesObj Any extended attributes for the device, as Key and Value pairs. Extended attributes are currently used for promotional codes and Verizon Partner Program lead information.

Keys
















Values

strings
















strings

The customer name and the address of the device's primary place of use.

PrimaryPlaceOfUseTitle
PrimaryPlaceOfUseFirstName
PrimaryPlaceOfUseMiddleName
PrimaryPlaceOfUseLastName
PrimaryPlaceOfUseSuffix
PrimaryPlaceOfUseAddressLine1
PrimaryPlaceOfUseAddressLine2
PrimaryPlaceOfUseCity
PrimaryPlaceOfUseState
PrimaryPlaceOfUseCountry
PrimaryPlaceOfUseZipCode
PrimaryPlaceOfUseZipCode4
PrimaryPlaceOfUseCBRPhone
PrimaryPlaceOfUseCBRPhoneType
PrimaryPlaceOfUseEmailAddress

The name, address, and contact information values for the current device.

Key

Value

string

string

PromoCodes: A comma-separated list of the names of any promotional codes active for the device.

A value of "Data=Machine to Machine 60KB" would indicate that a promotional code is associated with the device that allows for 60KB of complementary data traffic. Here are some example values:

  • Data=Machine to Machine 60KB
  • SMS=Machine to Machine 15 SMS
  • Voice=Machine to Machine 5 MOU

Key

Value

string

string

PromotionStartDate

The date that the promotion started, such as
4/1/2017 12:00:00 AM

Key

Value

string

string

PromotionScheduledEndDate

The date that the promotion is scheduled to end, such as
7/4/2017 12:00:00 AM

Keys










Values

strings










strings

Lead-related information for devices provisioned under a Silver, Member, or Limited tier VPP partner account:

LeadId
CustomerName
CustomerAddressLine1
CustomerAddressLine2
CustomerAddressCity
CustomerAddressState
CustomerAddressZipCode
ServiceZipCode

The values for the VPP partner account for the current device.

Key

Value

string

string

SkuNumber

The SKU for the current device.

Key

Value

string

string

CostCenterCode

The cost center code for the current device.

Key

Value

string

string

PreIMEI

The IMEI of the device prior to the most recent SIM OTA activation.

Key

Value

string

string

PreSKU

The SKU of the device prior to the most recent SIM OTA activation.

Key

Value

string

string

SIMOTADate

The date and time of the most recent SIM OTA activation.

Key

Value

string

string

RoamingStatus

Either "Roaming" or "NotRoaming" to indicate the device's current roaming status.

Key

Value

string

string

LastRoamingStatusUpdate

The date and time of the most recent RoamingStatus information.

Key

Value

string

string

RoamingCountry

The name of a country if RoamingStatus = Roaming, or empty if NotRoaming.

Example SOAP Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:v2="http://nphase.com/unifiedwebservice/v2"
  xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService"
  xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
  <soapenv:Header>
    <v2:token>2a855310-3c19-4a0d-978c-d29891f2112f</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:GetDeviceInformation>
      <v2:Input>
        <nph:Device>
          <nph1:Kind>meid</nph1:Kind>
          <nph1:Identifier>DAD20132013504</nph1:Identifier>
        </nph:Device>
      </v2:Input>
    </v2:GetDeviceInformation>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<GetDeviceInformationResponse xmlns="http://nphase.com/unifiedwebservice/v2">
   <Output xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService">
      <a:Device>
         <a:AccountName>Verizon Test 1</a:AccountName>
         <a:CarrierInformation>
            <a:CarrierInformation>
               <a:CarrierName>Verizon Wireless</a:CarrierName>
               <a:ServicePlan>M2M</a:ServicePlan>
               <a:State>suspend</a:State>
            </a:CarrierInformation>
         </a:CarrierInformation>
         <a:DeviceGroupName xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <b:string>Default: Verizon Test 1</b:string>
         </a:DeviceGroupName>
         <a:DeviceIdentifiers 
          xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
            <b:DeviceIdentifier>
               <b:Kind>mdn</b:Kind>
               <b:Identifier>3124705634</b:Identifier>
            </b:DeviceIdentifier>
            <b:DeviceIdentifier>
               <b:Kind>meid</b:Kind>
               <b:Identifier>DAD20132013504</b:Identifier>
            </b:DeviceIdentifier>
            <b:DeviceIdentifier>
               <b:Kind>min</b:Kind>
               <b:Identifier>8842730548</b:Identifier>
            </b:DeviceIdentifier>
         </a:DeviceIdentifiers>
         <a:CreatedAt>2013-04-12T20:20:03Z</a:CreatedAt>
         <a:IPAddress>1.1.30.77</a:IPAddress>
         <a:LastActivationDate>2013-04-12T20:20:05Z</a:LastActivationDate>
         <a:LastActivationBy>User Verizon</a:LastActivationBy>
         <a:BillingCycleEndDate>2013-05-01T00:00:00Z</a:BillingCycleEndDate>
         <a:Connected>false</a:Connected>
         <a:LastConnectionDate i:nil="true"/>
         <a:CustomFields i:nil="true"/>
         <a:FeatureCodes i:nil="true" xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common"/>
         <a:ExtendedAttributes 
          xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
            <b:ExtendedAttributesObj>
               <b:Key>PromoCodes</b:Key>
               <b:Value>Data=Machine to Machine 60KB,SMS=Machine to Machine 15 SMS</b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>PromotionStartDate</b:Key>
               <b:Value>12/3/2012 12:00:00 AM</b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>PromotionScheduledEndDate</b:Key>
               <b:Value>6/6/2013 12:00:00 AM</b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>LeadId</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>CustomerName</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>CustomerAddressLine1</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>CustomerAddressLine2</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>CustomerAddressCity</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>CustomerAddressState</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>CustomerAddressZipCode</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>ServiceZipCode</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>SkuNumber</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>CostCenterCode</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>PreIMEI</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>PreSKU</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>SIMOTADate</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>RoamingStatus</b:Key>
               <b:Value>NotRoaming</b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>LastRomaingStatusUpdate</b:Key>
               <b:Value>2/9/2017 9:28:34 PM</b:Value>
            </b:ExtendedAttributesObj>
            <b:ExtendedAttributesObj>
               <b:Key>RoamingCountry</b:Key>
               <b:Value></b:Value>
            </b:ExtendedAttributesObj>
         </a:ExtendedAttributes>
      </a:Device>
   </Output>
</GetDeviceInformationResponse>

Request Schema Diagram

Response Schema Diagram