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.

Retrieve a List of Account Leads:
GET /leads/{accountname}

Uses and Requirements

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

Call GET /leads to verify that the leads that need to be credited for pending activations (step 4) are associated with the account.
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.
Store the returned Lead IDs and their associated zipCode values.
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!