Leadsplease API Manual

Leadsplease API Manual ver. 1.3.4

Leadsplease API Manual

Authentication

Get Count

Get List

Create Lists Aggregation

TEST

Base URL: https://api-test.leadsplease.com/api/v1

Swagger UI: https://api-test.leadsplease.com/swagger-ui/index.html

LIVE

Base URL: https://api.leadsplease.com/api/v1

Swagger UI:  https://api.leadsplease.com/swagger-ui/index.html

For full request/response schemas and interactive testing, refer to the Swagger UI links above. 

Authentication

To get an authentication token, you need to call the Authentication API endpoint and pass your username and password in the request body.

A sample body:

A sample response:

If an endpoint requires authentication, a token should be included in the Authorization request header as a Bearer token. The token is valid for 20 minutes.

A sample header:

The following APIs require authentication:

1. Criteria API
2. Count API
3. List API
4. Lists Aggregation API

Get Count

Getting a Count includes the following steps:

1. Get supported demographics (optional)

Currently, the Consumer Dataset is described by 30+ demographics. Each demographic has a unique name and a set of values.

2. Create Criteria

Creating Criteria is a prerequisite for getting a Count and a List. Criteria may include demographics, geographies, or both.

Criteria has the following attributes:

• listType - the type of a list, one of consumer, business, newhomeowner, newmover.
• geoCriteriaType - the way a geography is selected, e.g. manual when a user provides a list of geographies (zip, city, county or state).
• affiliateCode - the affiliate code, e.g. lp.
• contactDataPoints - the array that allows you to specify which data points a user wants to get direct mail addresses. Supported values are direct_mail, email and phone. The contact data point direct_mail is always included in each and every list even if it was not specified for a given search criteria.

A geography is described by:

• name - it can be either a zip code, a city name, a county name or a state. Sample values: 85255, NEW YORK, AZ,
• type - Any of zip, city, county or state,
• state - the state abbreviation (e.g. AZ). If a type is a zip or a state then this attribute is optional.
• latitude / longitude and radius - the coordinates and search radius.

        A Criteria might include zero, one or more geographies.

A demographic is described by a name and an array of codes that represent selected values.

E.g. name = charityDonor, values = aw (Animal Welfare), ac (Arts or cultural)

Example 1 - Consumer sample demographic and geographic criteria:

Example 2 - radial search:

When a Criteria has been successfully created, a user gets their unique ID in a response.

Example 3 -  Business sample demographic and geographic criteria:

Example 4 -  Newmover sample demographic and geographic criteria:

Example 5 -  New homeowner search criteria when a list should include direct mail, emails and phones.

Example 6 - polygon search:

3. Get Count

        Get a Count for a given Criteria.

        Note: Count requests are limited to 10 requests per minute.

Get List

Getting a List includes the following steps:

1. Create Criteria

This is an optional step. The same criteria that were created for the Get Count request can be used.

2. Get Count 

Get a Count for given criteria to know the maximum number of available leads.

3. Get List

1. Create List

Call the Create List endpoint to trigger List creation. The response will include a URL to an endpoint that allows you to check the list creation status.

2. Check List Status

When List creation is triggered, the status is Pending. Once the CSV file is generated, the status changes to Completed and the response also includes a URL to download the file.                 

3. Get a File

Use the URL returned by the Check List Status endpoint to download the CSV file.

Create Lists Aggregation

The Lists Aggregation API allows you to group lists together, making it possible to download many List files as a single file.

1. Create List Aggregation

A List Aggregation can be identified by its ID and name. It enables you to download a file that merges multiple list files.

Once a List Aggregation is created, you receive a URL to check the status of the aggregated list generation. Once the file is generated, the response will also include a URL to download it.

2. Download a file

        Download a CSV file that merges multiple List files.

3. Remove List from Aggregation

Remove a List from a given Aggregation. If a List Aggregation file was previously generated, it will be regenerated.

4. Add List to Aggregation

Add a List to a given Aggregation. If a List Aggregation file was generated earlier, it will be regenerated.

Get All Demographics

To get all demographics for a given dataset call the following URL (GET):

<Base URL>/demographic-categories?type=<Dataset>&affiliateCode=<AffiliateCode>

Where ListType is one of consumer, business, newhomeowner, newmover.

E.g. https://api-test.leadsplease.com/api/v1/demographic-categories?type=newmover&affiliateCode=lp

Get all SIC codes with description

To get a list of all SIC codes and their descriptions call the following URL (GET):

<Base URL>/sic-codes

Find SIC code by Keyword

To find a SIC code(s) by a description call the following URL (GET):

<Base URL>/api/v1/sic-codes/search?description=<Description>

Where description is a keyword or a part of a keyword.

E.g. https://api-test.leadsplease.com/api/v1/sic-codes/search?description=Restaurant

Subscription

Subscriptions allow you to periodically receive fresh New Homeowner and New Mover leads.

Each subscription run delivers only newly loaded records that have not yet been included in previous runs, and creates a new order. A daily check verifies whether new data has been loaded since the last subscription run.

A subscription uses the search criteria defined when it was created. The generated CSV file is delivered via the configured delivery channels. Currently, only EMAIL is supported.

Create Subscription

To create a Subscription call the following URL (POST):

<Base URL>/subscriptions

The userId is the user identifier that you received from the LeadsPlease technical team.

The successful response includes a subscriptionId.

Example 7. Create a new subscription.

Get Subscriptions

To list a Subscription call the following URL (GET):

<Base URL>/subscriptions

To get a Subscription by its ID call the following URL (GET):

<Base URL>/subscriptions/{subscriptionId}

Delete Subscription

To delete a Subscription by its ID call the following URL (DELETE):

<Base URL>/subscriptions/{subscriptionId}