GoToState

Changes the provisioning state of one or more devices to a specified customer-defined service and state.

NOTE: This API method can only be used by customers who are on the IoT Workflow or IoT Order Flow, and that have custom states and services defined for their account. Contact Customer Support or your Verizon Sales Representative for additional information.

Uses and Requirements

You should be familiar with the M2M Service Provisioning Rules when working with device states.

The ThingSpace Platform sends an asynchronous GoToState callback message for each device in the request when the request has been completed, or if there was a problem and the change failed.

You can specify a list of individual 3G or 4G devices, or work with all 3G or 4G devices in an account or device group. You cannot mix 3G and 4G devices in the same request; only one type will be changed and devices of the other type will fail.

All devices in the request are assumed to be in the same state as the first device in the request. If any of the other devices are not in the same state as the first device, an error will be returned in the callback for that device.

Best Practices

In addition to receiving StateService callback messages, you can use GetDeviceInformation to check the status of the device and GetDeviceProvisioningHistory to see details of completed GoToState requests.

Request Parameters

Parameter Type Description
DeviceList
optional*		 DeviceIdentifierCollection

A list of the devices that you want to push to a different state, specified by device identifier. Do not pass DeviceGroupNameFilter, AccountNameFilter, DeviceCustomFieldFilter, or DeviceServicePlanFilter if you use this parameter.

NOTE: Specify only 4G devices or 2G/3G devices in each request. You cannot change 4G devices and 2G/3G devices in the same request.

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

For each device in DeviceList, use this structure of nested parameters: 

<DeviceIdentifierCollection>
  <DeviceIndentifiers>
    <DeviceIdentifier>
      <Kind></Kind>
      <Identifier></Identifier>
    </DeviceIdentifier>
  </DeviceIndentifiers>
</DeviceIdentifierCollection>
DeviceList.Kind
required for DeviceList		 string

The type of the device identifier. Valid types of identifiers are:

  • ESN (decimal)
  • EID
  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN

The types of identifiers that are required depend on your device types and whether you are activating the devices or pushing them to some non-active state.

  • To push 2G or 3G devices to an active state, you only need to include either the ESN or MEID.

  • There are several options for pushing 4G devices to an active state:

    • If the devices do not have embedded SIMs, you must specify both the IMEI and the ICCID within separate DeviceIdentifier elements, in that order.
    • If the devices have embedded SIMs, you can specify IMEI and ICCID values, or just the ICCIDs and an associated device SkuNumber.
    • If the devices are eUICC devices, you can specify the EID and IMEI values, or the EIDs and an associated SkuNumber.
DeviceList.Identifier
required for DeviceList		 string The value of the device identifier.
AccountNameFilter
required for activation states		 string

The name of a billing account, which can serve one of two purposes:

  • If you want to push all devices in an account.
  • If you are passing DeviceServicePlanFilter or DeviceCustomFieldFilter, you must include the name of the billing account.

An account name is usually numeric, and must include any leading zeros.
DeviceGroupNameFilter
optional*		 string

The name of a device group if you want to only include devices in that group.

NOTE: You can use GetDeviceGroupList to get a list of all device groups in the account.
DeviceServicePlanFilter
optional*		 string

A service plan code, if you want to only include devices that have that service plan.

NOTE: You can use GetServicePlanList to get a list of all service plans in the account.
DeviceCustomFieldFilter
optional*		 CustomFieldFilterObject The names and values of custom fields, if you want to only include devices that have matching custom fields.
DeviceCustomFieldFilter.Name
required for DeviceCustomFieldFilter		 string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
DeviceCustomFieldFilter.Value
required for DeviceCustomFieldFilter		 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)
ServiceName
required		 string The name of a customer-defined service to push the devices to.
StateName
required		 string The name of a customer-defined stage state to push the devices to.
ServicePlan
required		 string

The service plan code that you want to assign to all specified devices in the new state. Set this parameter to one of the Code values returned by GetServicePlanList in the Account Service.

NOTE: Any devices in the request that are not supported by the service plan will not activate. For example, if the service plan is only for 4G devices, any 3G devices included in the GoToState request will fail.

CarrierIpPoolName
optional		 string The pool from which your device IP addresses will be derived if the service or state change requires new IP addresses. If you do not include this element, the default pool will be used.
MdnZipCode
optional		 string The Zip code of the location where the line of service will primarily be used, or a Zip code that you have been told to use with these devices. For accounts that are configured for geographic numbering, this is the ZIP code from which the MDN will be derived.
CustomFields
optional		 CustomField The names and values of any custom fields that you want to set for the devices after the state change.
CustomFields.Name
required for CustomFields		 string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
CustomFields.Value
required for CustomFields		 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)
DeviceGroupNames
optional		 string The name of a device group that the devices should be added to after the state change.
PublicIPRestriction
optional		 string

For 3G devices with static IP addresses on the public network, this specifies whether the devices have general access to the Internet. Valid values are "restricted" or "unrestricted".

  • Unrestricted = The devices will have full access to the Internet.
  • Restricted = The devices will have access to any content provided by Verizon Wireless but will be restricted from access to the Internet.

If left blank, the devices will get the default value set for the account. Public network devices with dynamic IP addresses are always unrestricted.
SkuNumber
optional		 string

The Stock Keeping Unit (SKU) of a 4G device type can be used with ICCID device identifiers in lieu of an IMEI when activating 4G devices.

The SkuNumber will be used with all devices in the request, so all devices must be of the same type.
PrimaryPlaceOfUse
optional		 PrimaryPlaceOfUse

The customer name and the address of the device's primary place of use. Leave these fields empty to use the account profile address as the primary place of use. These values will be applied to all devices in the GoToState request.

If the account is enabled for non-geographic MDNs and the device supports it, the PrimaryPlaceOfUse address will also be used to derive the MDN for the device.

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.

NOTE: Primary Place of Use may be required for some state changes.
PrimaryPlaceOfUse.CustomerName
required for PrimaryPlaceOfUse		 PrimaryPlaceOfUseCustomerName The customer name to be used when contacting the customer and for line usage taxation.
PrimaryPlaceOfUse.CustomerName.Title
optional		 string An optional title for the customer, such as "Mr." or "Dr."
PrimaryPlaceOfUse.CustomerName.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.
PrimaryPlaceOfUse.CustomerName.MiddleName
optional		 string The customer's middle name.
PrimaryPlaceOfUse.CustomerName.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.
PrimaryPlaceOfUse.CustomerName.Suffix
optional		 string An optional suffix for the customer name, such as "Jr." or "III."
PrimaryPlaceOfUse.Address
required for PrimaryPlaceOfUse		 PrimaryPlaceOfUseAddress The customer address for the line's primary place of use, for line usage taxation.
PrimaryPlaceOfUse.Address.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.
PrimaryPlaceOfUse.Address.AddressLine2
optional		 string Optional additional street address information.
PrimaryPlaceOfUse.Address.City
required for Address		 string The city for the line's primary place of use.
PrimaryPlaceOfUse.Address.State
required for Address		 string The state for the line's primary place of use. If a state name is provided, it will be converted to the standard 2-digit state code.
PrimaryPlaceOfUse.Address.ZipCode
required for Address		 string The five digit Zip code for the line's primary place of use. If Zip code is passed in Zip-Zip4 format, the Zip code will be kept and the Zip4 code will be stored in the Zip4.
PrimaryPlaceOfUse.Address.Country
required for Address		 string Either "US" or "USA" for the country of the line's primary place of use.
PrimaryPlaceOfUse.Address.ZipCode4
optional		 string the four digit Zip code in the Zip-Zip4 format.
PrimaryPlaceOfUse.Address.CBRPhone
optional		 string A phone number where the customer can be reached (CBR).
PrimaryPlaceOfUse.Address.CBRPhoneType
optional		 string

A single letter to indicate the customer phone type:

  • M = Mobile
  • H = Home
  • F = Fax
  • W = Work/Business
  • P = Pager
PrimaryPlaceOfUse.Address.EmailAddress
optional		 string An email address for the customer.

* You can either specify individual devices with the DeviceList parameter, or you can run the request on all devices that have a specified account name, device group name, service plan, or custom field value. You can use multiple filters to select only those devices that match all criteria.

Response Parameters

Parameter Type Description
RequestId string

A unique string that associates the request with the results that are sent via a callback service.

The ThingSpace Platform will send 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 will have the same RequestId.

Callback Response Parameters

Parameter Type Description
CallbackRequest CallbackRequest Wrapper element for all callback elements.
Username string The username defined when a URL was registered for the callback service, or an empty element if no username was defined.
Password string The password defined when a registered for the callback service, or an empty element if no password was defined.
RequestId string A unique string that matches the RequestId returned in the synchronous response to the original API request.

A separate callback message is sent for each device that matched the request criteria, indicating whether the operation succeeded for that device. All of the callback messages will have the same RequestId.
Device DeviceIdentifier The device that was changed.
Kind string The type of the device identifier. Valid types of identifiers are:
  • EID
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • IMSI
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
Data CallbackData The data elements for this callback.
CarrierService CarrierServiceCallbackRequest Null for this callback service.
ExternalProvisioningChange ExternalProvisioningChange Null for this callback service.
PromoChange PromoChange Null for this callback service.
SMSDelivery SMSDelivery Null for this callback service.
PRLInformation PRLInformation Null for this callback service.
DeviceSuspendStatus DeviceSuspendStatus Null for this callback service.
DeviceService DeviceService Null for this callback service.
GoToState GoToStateCallbackRequest The updated information for the device that was pushed to a new state.
DeviceIdentifierCollection DeviceIdentifier Identifiers for the device that was pushed to a new state. The callback may include multiple identifiers for the same device, such as the ESN and the MDN.
Kind string The type of the device identifier. Valid types are:
  • EID
  • 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.
IpAddress string The IP address of the device.
StateName string The new provisioning state of the device.
ServiceName string The new service name for the device.
ServicePlan string The new service plan for the device.
AccountName string The new account name for the device.
SmsrOid string The Object ID of the SMSR system.
SubscriptionTypeCode string Valid value include:
  • GPX - Garage Swap with Pre-Paid External Subscriber
  • GPV - Garage Swap with Postpaid Verizon Subscriber
SubscriptionTypeDesc string A description of the SubscriptionTypeCode.
StageStateChangeReasonCode string 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
StageStateChangeReasonDesc string A description of the StageStateChangeReasonCode.
Fault SoapFault Information about any errors that may have occurred.
faultcode QName
faultstring string
faultfactor anyURI
detail
Comment string Null in GoToState callback messages.
Summary SummaryReport Null for this callback service.
Status string Success or Failed.
CallbackCount integer The number of times this callback message has been sent.
MaxCallbackThreshold integer The maximum number of times this callback message will be sent if it is not correctly acknowledged.

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.StateService">
  <soapenv:Header>
    <v2:token>fa59c858-833e-4a4e-a6a8-56f382abcdd5</v2:token>
  </soapenv:Header>
   <soapenv:Body>
      <v2:GoToState>
         <v2:Input>
            <nph:DeviceList>
               <nph1:DeviceIdentifierCollection>
                  <nph1:DeviceIdentifiers>
                     <nph1:DeviceIdentifier>
                        <nph1:Kind>iccid/nph1:Kind>
                        <nph1:Identifier>89144259800000080079</nph1:Identifier>
                     </nph1:DeviceIdentifier>
                  </nph1:DeviceIdentifiers>
               </nph1:DeviceIdentifierCollection>
            </nph:DeviceList>
            <nph:AccountNameFilter>0212354321-00001M</nph:AccountNameFilter>
            <nph:ServiceName>fast1</nph:ServiceName>
            <nph:StateName>inter-active</nph:StateName>
            <nph:ServicePlan>4G East</nph:ServicePlan>
         </v2:Input>
      </v2:GoToState>
   </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<GoToStateResponse xmlns="http://nphase.com/unifiedwebservice/v2">
   <Output xmlns:a="http://schemas.datacontract.org/2004/07NPhase.UnifiedWebService.APIs.v2.Contract.StateService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <a:RequestId>2c90bd28-ece4-42ef-9f02-7e3bd4fbff33</a:RequestId>
   </Output>
</GoToStateResponse>

Example SOAP Callback

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
    <Username xmlns="http://nphase.com/unifiedwebservice/v2">toyota_multipleenv</Username>
<Password xmlns="http://nphase.com/unifiedwebservice/v2">Verizon*16</Password>
<RequestId xmlns="http://nphase.com/unifiedwebservice/v2">6e3811c2-cbac-474a-9a11-25399d75b190</RequestId>
<Device xmlns="http://nphase.com/unifiedwebservice/v2">
	<Kind>IMEI</Kind>
	<Identifier>897379503082459</Identifier>
</Device>
<Data xmlns="http://nphase.com/unifiedwebservice/v2">
	<Data xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://nphase.com/unifiedwebservice/v2">
		<CarrierService xsi:nil="true" />
		<ExternalProvisioningChange>
			<Source xsi:nil="true" />
			<Change>goToStateWithMtn</Change>
			<DeviceInfo>
				<AccountName>WAMmultipleacc1</AccountName>
				<CarrierInformation>
					<CarrierName>Verizon Wireless</CarrierName>
					<ServicePlan>1312</ServicePlan>
					<State>active</State>
				</CarrierInformation>
				<DeviceGroupName>Default: WAMmultipleacc1</DeviceGroupName>
				<DeviceIdentifiers>
					<Kind>mdn</Kind>
					<Identifier>0400218481</Identifier>
				</DeviceIdentifiers>
				<DeviceIdentifiers>
					<Kind>imsi</Kind>
					<Identifier>311480107643943</Identifier>
				</DeviceIdentifiers>
				<DeviceIdentifiers>
					<Kind>imei</Kind>
					<Identifier>897379503082459</Identifier>
				</DeviceIdentifiers>
				<DeviceIdentifiers>
					<Kind>iccId</Kind>
					<Identifier>31980173919897667701</Identifier>
				</DeviceIdentifiers>
				<DeviceIdentifiers>
					<Kind>msisdn</Kind>
					<Identifier>10400218481</Identifier>
				</DeviceIdentifiers>
				<DeviceIdentifiers>
					<Kind>min</Kind>
					<Identifier>0400218481</Identifier>
				</DeviceIdentifiers>
				<CreatedAt>2021-05-18T16:58:45.0000000Z</CreatedAt>
				<IPAddress xsi:nil="true" />
				<LastActivationDate>2021-05-18T16:58:46.0000000Z</LastActivationDate>
				<LastActivationBy>Mtas User</LastActivationBy>
				<BillingCycleEndDate>2021-05-31T00:00:00.0000000Z</BillingCycleEndDate>
				<Connected>false</Connected>
				<LastConnectionDate xsi:nil="true" />
				<PreIMEI xsi:nil="true" />
				<PreSKU xsi:nil="true" />
				<SIMOTADate xsi:nil="true" />
			</DeviceInfo>
			<StateName>WAM Activate</StateName>
			<ServiceName>WAM</ServiceName>
			<ServiceAccount>WAMmultipleacc1</ServiceAccount>
			<SubscriptionTypeCode>GPX</SubscriptionTypeCode>
			<SubscriptionTypeDesc>Garage Swap with Pre-Paid External Subscriber</SubscriptionTypeDesc>
			<StageStateChangeReasonCode></StageStateChangeReasonCode>
			<StageStateChangeReasonDesc></StageStateChangeReasonDesc>
		</ExternalProvisioningChange>
		<PromoChange xsi:nil="true" />
		<SMSDelivery xsi:nil="true" />
		<PRLInformation xsi:nil="true" />
		<DeviceService xsi:nil="true" />
		<GoToState xsi:nil="true" />
		<DeviceProfileService xsi:nil="true" />
		<AlertService xsi:nil="true" />
		<InternalService xsi:nil="true" />
		<DiagnosticsService xsi:nil="true" />
		<Fault xsi:nil="true" />
		<Comment xsi:nil="true" />
		<Summary xsi:nil="true" />
		<Status>Success</Status>
		<CallbackCount>1</CallbackCount>
		<MaxCallbackThreshold>4</MaxCallbackThreshold>
		<ExtendedEnhancedConnectivityService xsi:nil="true" />
		<NiddService xsi:nil="true" />
		<ScefMonteEvent xsi:nil="true" />
	</Data>
</Data>
</CallbackRequest>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram