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.
Device.Kind
required		 string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN
Device.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 ThingSpace 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)
  • EID
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
CreatedAt dateTime string 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 and time that the device's current billing cycle ends.
Connected boolean True if the device is connected; false if it is not.
LastConnectionDate dateTime The most recent connection date and time (Zulu time).
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 2MB for 8 Months
  • 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/2019 12:00:00 AM

Key

Value

string

string

PromotionScheduledEndDate

The date that the promotion is scheduled to end, such as
7/4/2019 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.

Key

Value

string

string

SmsrOid

For eUICC devices, the Object ID of the SMSR system.

Key

Value

string

string

ProfileStatus

For eUICC devices, the current status of the local profile. Nil for all other devices.

Key

Value

string

string

AccountNumber

The billing account number that the device is associated with. It is usually the same as the AccountName.

Keys


Values

strings


strings

ServiceNameN
StateNameN

The names of services and states active for a device in an account that has custom services and states. StateName1 belongs to ServiceName1, and StateName2 belongs to ServiceName2, etc.

Keys


Values

strings


strings

ServiceStartDateN

The service start date, such as 2021-05-25T02:17:59Z. ServiceStateStartDate1 belongs to ServiceName1 and StateName1 , and ServiceStateStartDate2 belongs to ServiceName2 and StateName 2, etc.,

Keys


Values

strings


string

SubscriptionTypeCodeN

Valid value include:

  • GPX - Garage Swap with Pre-Paid External Subscriber
  • GPV - Garage Swap with Postpaid Verizon Subscriber

Keys


Values

strings


string

SubscriptionTypeDescN

A description of the SubscriptionTypeCode.

Keys


Values

strings


string

StageStateChangeReasonCodeN

Valid values include:

  • OTE - On Demand Trial End
  • SUB - Ended Subscription
  • EXT - Expired Trial
  • APT - Activated Post Paid WiFi Service
  • APP - Activated Prepaid WiFi Service

Keys


Values

strings


string

StageStateChangeReasonDesc1

A description of the StageStateChangeReasonCode.

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 

    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
       <s:Body>
          <GetDeviceInformationResponse xmlns="http://nphase.com/unifiedwebservice/v2">
             <Output xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
                <a:Device>
                   <a:AccountName>0542182099-00001</a:AccountName>
                   <a:CarrierInformation>
                      <a:CarrierInformation>
                         <a:CarrierName>Verizon Wireless</a:CarrierName>
                         <a:ServicePlan>18337</a:ServicePlan>
                         <a:State>active</a:State>
                      </a:CarrierInformation>
                   </a:CarrierInformation>
                   <a:DeviceGroupName xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                      <b:string>Default: 0542182099-00001</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>5249266472</b:Identifier>
                      </b:DeviceIdentifier>
                      <b:DeviceIdentifier>
                         <b:Kind>imsi</b:Kind>
                         <b:Identifier>311480959560052</b:Identifier>
                      </b:DeviceIdentifier>
                      <b:DeviceIdentifier>
                         <b:Kind>iccId</b:Kind>
                         <b:Identifier>89148000006926826155</b:Identifier>
                      </b:DeviceIdentifier>
                      <b:DeviceIdentifier>
                         <b:Kind>msisdn</b:Kind>
                         <b:Identifier>15249266472</b:Identifier>
                      </b:DeviceIdentifier>
                      <b:DeviceIdentifier>
                         <b:Kind>min</b:Kind>
                         <b:Identifier>5249266472</b:Identifier>
                      </b:DeviceIdentifier>
                      <b:DeviceIdentifier>
                         <b:Kind>eid</b:Kind>
                         <b:Identifier>89033023312150000000004704952127</b:Identifier>
                      </b:DeviceIdentifier>
                   </a:DeviceIdentifiers>
                   <a:CreatedAt>2021-05-20T18:25:20Z</a:CreatedAt>
                   <a:IPAddress i:nil="true"/>
                   <a:LastActivationDate>2021-05-20T18:25:53Z</a:LastActivationDate>
                   <a:LastActivationBy>John Q Smith</a:LastActivationBy>
                   <a:BillingCycleEndDate>2021-05-31T00: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>AccountNumber</b:Key>
                         <b:Value>0542182099-00001</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>SmsrOid</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>ProfileStatus</b:Key>
                         <b:Value>Not Downloaded</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>PromoCodes</b:Key>
                         <b:Value/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>PromotionStartDate</b:Key>
                         <b:Value/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>PromotionScheduledEndDate</b:Key>
                         <b:Value/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>LeadId</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>CustomerName</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>CustomerAddressLine1</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>CustomerAddressLine2</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>CustomerAddressCity</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>CustomerAddressState</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>CustomerAddressZipCode</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>ServiceZipCode</b:Key>
                         <b:Value>73010</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>SkuNumber</b:Key>
                         <b:Value>VZW086828310022</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>CostCenterCode</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>PreIMEI</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>PreSKU</b:Key>
                         <b:Value i:nil="true"/>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>RoamingStatus</b:Key>
                         <b:Value>Unavailable</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>ServiceName1</b:Key>
                         <b:Value>VW B2B</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>StateName1</b:Key>
                         <b:Value>VW B2B Inservice</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>ServiceStateStartDate1</b:Key>
                         <b:Value>2021-05-25T02:17:59Z</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>SubscriptionTypeCode1</b:Key>
                         <b:Value>GPX</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>SubscriptionTypeDesc1</b:Key>
                         <b:Value>Garage Swap with Pre-Paid External Subscriber</b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>StageStateChangeReasonCode1</b:Key>
                         <b:Value></b:Value>
                      </b:ExtendedAttributesObj>
                      <b:ExtendedAttributesObj>
                         <b:Key>StageStateChangeReasonDesc1</b:Key>
                         <b:Value></b:Value>
                      </b:ExtendedAttributesObj>
                   </a:ExtendedAttributes>
                </a:Device>
             </Output>
          </GetDeviceInformationResponse>
       </s:Body>
    </s:Envelope>

Request Schema Diagram

Response Schema Diagram