API Reference

`POST /v1/devices/profile/actions/activate`

Activate and reserve a Verizon eUICC profile for Consumer eSIM SGP.22 capable devices. This endpoint supports both use cases, reserving new Verizon eUICC profiles as well reactivating previously downloaded eUICC profiles, for which the subscription has been previously deactivated. Note: Upon reservation of a profile, the Integrated Circuit Card ID (ICCID) gets created in our backend systems. Activation code provided can then be used by the device to reach out to Verizon’s Subscription Manager Data Preparation+ (SM-DP+), to download and eventually install the carrier profile. Once downloaded and installed, the profile can be enabled by the end-user or automatically by the device. Some Verizon pricing plans, in particular Unlimited 5G Business Internet (5G BI) Plans, require address validation. For such requests, a deviceWithServiceAddress object is required.

Header Parameters

The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.

Parameter Name	Data Type	Description
Authorization (required)	string	HTTP Authorization bearer token: `Authorization: Bearer {token}`
VZ-M2M-Token (required)	string	A valid session token: `VZ-M2M-Token: {M2Mtoken}`
Content-Type (required)	string	Must be application/json `Content-Type: application/json`

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/profile/actions/activate

Request Parameters

Parameter	Data Type	Description
devicesWithService Address	object	An object that contains an array of device IDs and Primary Place of Use for Fixed Wireless Access plans.
deviceIds	array	An array of device identifer values. Each pair of values will contain an `id` and`kind`.
id	string	The numeric ID of the device.
kind	string	The type of device ID represented by the ID value. Depending on the activation request, only EID , IMEI and ICCID values are accepted.
primaryPlaceOfUse (PPU) (required)	object	The customer name and the address of the device’s primary place of use. For 5G BI price plans, this address will be used for qualification before the activation will complete. 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.
customerName (required for PPU)	object	The customer name to be used for line usage taxation.
title (optional for customerName)	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 for customerName)	string	The customer’s middle name. Values follow the same rules as `firstName`.
lastName (required for customerName)	string	The customer’s last name or Surname. Values follow the same rules as `firstName`.
suffix (optional for customerName)	string	An optional suffix for the customer name, such as “Jr.” or “III.”.
address (required for PPU)	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 for address)	string	Optional additional street address information (suite, room, building, etc.).
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. If a state name is provided, it will be converted to the ISO standard 2-digit state code.
zip (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 `zip4`.
zip4 (optional for address)	string	The four digit Zip code in the Zip-Zip4 format.
country (required for address)	string	Either “US” or “USA” for the country of the line’s primary place of use.
phone (optional for address)	string	A 10-digit phone number where the customer can be reached.
phoneType (optional for address)	string	A single letter to indicate the customer phone type: M = Mobile H = Home F = Fax W = Work/Business P = Pager
emailAddress (optional for address)	string	An email address for contacting the customer.
carrierName	string	The name of the carrier providing cellular network access. Verizon Wireless is the default.
accountName (required)	string	The name of the account. This is numeric and is in the format 0000123456-00001. Leading zeros must be included.
servicePlan	string	The service plan the account is subscribed to. This drives billing for usage.
mdnZipCode	string	The 5-digit zip code of the profile.

Request Body

Example request:

{
   "devicesWithServiceAddress":[
    {
       "deviceIds":[
          {               
             "kind":"imei",
             "id":"15-digit IMEI"
          },
          {
             "kind":"eid",
             "id":"32-digit EID"
          }
       ],
       "primaryPlaceOfUse":{
          "address":{
             "addressLine1":"1 Drive",
             "city":"Big Town",
             "state":"TX",
             "country":"USA",
             "zip":"00000",
             "zip4":"",
             "phone":"10-digit phone number",
             "phoneType":"M",
             "emailAddress":"name@email.com"
          },
          "customerName":{
             "firstName":"first name",
             "lastName":"last name"
          }
       }
    }
 ],
"carrierName": "Verizon Wireless",
"accountName":"0000123456-00001",
"servicePlan":"5GPlan",
"mdnZipCode":"00000"
}

An example request for a reactivation:

{
   "devicesWithServiceAddress":[
    {
       "deviceIds":[
          {               
             "kind":"imei",
             "id":"15-digit IMEI"
          },
          {
            "kind":"iccid",
            "id":"20-digit ICCID"
         },
          {
             "kind":"eid",
             "id":"32-digit EID"
          }
      ],
    }
 ],
"carrierName": "Verizon Wireless",
"accountName":"0000123456-00001",
"servicePlan":"5GPlan",
"mdnZipCode":"00000"
}

Success Response

Status 200 A successful response shows a system generated request ID to track the request. Example Response:

{
  "requestId": "d1f08526-eeee-ffff-gggg-4456490ea9f8"
}

Callback Response

These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit About About Callback Services. The callback that must be subscribed to is DeviceProfileService. Example callback responses:

First Activation Response:

{
   "requestId":"d1f08526-eeee-ffff-gggg-4456490ea9f8",
   "deviceIds":[
      {
         "id":"32-digit EID",
         "kind":"eid"
      },
      {
         "id":"15-digit IMEI",
         "kind":"imei"
      },
      {
         "id":"10-digit MDN",
         "kind":"mdn"
      },
      {
         "id":"20-digit ICCID",
         "kind":"iccid"
      }
   ],
   "deviceResponse":{
      "deviceProfileResponse":{
         "deviceIdentifierCollection":[
            {
               "id":"32-digit EID",
               "kind":"eid"
            },
            {
               "id":"15-digit IMEI",
               "kind":"imei"
            },
            {
               "id":"10-digit MDN",
               "kind":"mdn"
            },
            {
               "id":"20-digit ICCID",
               "kind":"iccid"
            }
         ],
         "state":"ACTIVE",
         "servicePlan":"service plan name",
         "deviceCredential":{
            "username":"user name",
            "password":"password"
         },
         "profileStatus":"UNKNOWN",
         "carrierName":"Verizon Wireless",
         "profileRole":"LOCAL"
      }
   },
   "status":"SUCCESS",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Second Activation Response

{
   "requestId":"d36bdf9e-eeee-ffff-gggg-a662c2cd7cdc",
   "deviceIds":[
      {
         "id":"10-digit MDN",
         "kind":"mdn"
      }
   ],
   "deviceResponse":{
      "deviceProfileResponse":{
         "deviceIdentifierCollection":[
            {
               "id":"10-digit MDN",
               "kind":"mdn"
            }
         ],
         "state":"ACTIVE",
         "profileStatus":"UNKNOWN",
         "profileRole":"LOCAL",
         "activationCode":"A system generated code"
      }
   },
   "status":"SUCCESS",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Callback Parameters

Parameter	Data Type	Description
requestId	string	The `requestId` being viewed. This is a system generated value (UUID) from the activation request.
deviceIds	array	An array of devices being queried by the request. Each `deviceId` will contain: `id`, `kind`
id	string	The numeric ID of the device.
kind	string	The type of device ID represented by the ID value. This could be: imei, iccid, mdn or eid.
deviceResponse	array	Contains the `deviceProfileResponse`, `status` and number of callback records returned.
deviceProfileResponse	array	Contains the details and status of the devices and the request.
deviceIdentifierCollection	array	Similar to `deviceIds` above, but this lists the devices responding.
state	string	The state of the device(s) responding.
profileStatus	string	Indicates the profile state.
profileRole	string	Indicates if the profile used is Verizon (local) or Global (remote).
activationCode	string	A system generated code for activating this device.
status	string	The status of the `deviceResponse`.
callbackCount	string	The number of responses for `deviceResponse` found.
maxCallbackThreshold	string	The maximum number of responses for `deviceResponse` allowed.

Failure Responses

All error responses will be in the following format

{
  "errorCode": "The 3-digit HTML error code",
  "errorMessage": "string"
}

POST /v1/devices/profile/actions/activateCopy Anchor Link

Header ParametersCopy Anchor Link

HTTP RequestCopy Anchor Link

Request ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Success ResponseCopy Anchor Link

Callback ResponseCopy Anchor Link

First Activation Response:Copy Anchor Link

Second Activation ResponseCopy Anchor Link

Callback ParametersCopy Anchor Link

Failure ResponsesCopy Anchor Link

On this page