Retrieve a List of Account Leads:

GET /leads/{accountname}

Returns information for all leads associated with an account. The lead information comes from the Verizon Partner Resource Management (PRM) tool. If the information is incomplete or inaccurate, you must use the PRM tool to update it, and it will be synchronized with the ThingSpace Platform within an hour.

This API is for use by Verizon Partner Program (VPP) partners only.

Contents

Uses and Requirements

Use this resource along with the POST /devices/actions/activate request to credit service activations to the right leads for compensation.

  1. Call GET /leads to verify that the leads that need to be credited for pending activations (step 4) are associated with the account.
  2. If a lead is not associated with the account, verify that it has been entered in the PRM tool. Lead information is synchronized between the PRM tool and the ThingSpace Platform every hour, so you may need to wait a short time before information about new leads is returned by the /leads resource.
  3. Store the returned Lead IDs and their associated zipCode values.
  4. When you send a POST /devices/actions/activate request to activate devices, you must include the ID of the lead to be compensated in the leadId parameter, and put the zipCode value associated with that lead in the mdnZipCode parameter. (The mdnZipCode value is used when calculating compensation.)

Lead IDs do not change, so only repeat steps 1-3 when new leads are qualified for the account.

Request Components

HTTP Request

GET https://thingspace.verizon.com/api/m2m/v1/leads/{accountname}?{next}

Resource and Query Parameters

You must include the account name in the path.

Parameter Name Data Type Description
accountname
required
string The name of the account for which a list of leads will be returned. An account name is usually numeric, and must include any leading zeros.
next
optional
int64 The next value returned in the Location header of the previous GET response. Each response will contain a maximum of 1,000 leads. If the account has more than 1,000 leads, you must specify a value for next to get the next block of leads.
  • For the first request, do not include this parameter to retrieve the first block of leads.
  • If the response is status 200 and hasMoreData=true, use the URL from the Location header in the response to send another GET request. The Location URL contains the correct value for the next parameter.

    For example, https://thingspace.verizon.com/api/m2m/v1/leads/{{account}}?next=1001

  • Continue sending requests with the latest Location URL, or incrementing the next value by 1,000, until you receive a status 200 response with hasMoreData=false, which indicates that you have received all of the leads.

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

None.

Success Responses

Status 200

A successful request returns an array of lead objects that contain these values:

Parameter Name Data Type Description
leads array of lead objects The leads associated with an account.
leadId
string Unique number for each lead. Use this value in the leadId parameter when activating devices to credit the activations to the lead.
leadState
string The current state of the lead, such as “Qualified” or “Closed.”
address
  Any extended attributes for the service plan, as Key and Value pairs.
addressLine1
addressLine2
city
state
zip
strings Separate strings containing the address information for the lead. This information is used to set the Primary Place of Use fields that are sent to other Verizon systems during device activation.
Note: The ThingSpace Platform also stores the Customer First Name and Last Name, but those fields are not shown.
hasMoreData boolean False if no more leads.
True if there is more data to be retrieved. Send another request and include the next parameter to get the next block of leads.

Example Success Response

{
  "leads": [
    {
      "leadId": "L-10001",
      "leadState": "Qualified",
      "address": {
        "addressLine1": "1600 Pennsylvania Avenue",
        "addressLine2": "",
        "city": "Washington",
        "state": "DC",
        "zip": "20500"
      }
    },
    {
      "leadId": "L-10003",
      "leadState": "Closed",
      "address": {
        "addressLine1": "2000 Las Vegas Blvd S",
        "addressLine2": "",
        "city": "Las Vegas City",
        "state": "Nevada",
        "zip": "89104-0001"
      }
    }
  ],
  "hasMoreData": false
}

Failure Responses

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

Try It Out!