Lead API Documentation – v1

Summary

Leads API will provide methods for querying and manipulating the Leads database both internally as well as externally through provided security credentials

Generating API access keys

API keys can only be generated by user accounts with the ‘edit_users’ capability enabled, which is encompassed by the ‘Administrator’ user role.

To generate a set of API keys head into wp-admin->Leads->Global Settings->API Keys.

API_Keys

 

Types of Keys

Public

This is the main api key to be used when authenticating. You could consider it the username, while the token is the password.

This key still should not be shared with the public but if it gets compromised it will not mean another can tamper with your installation through the API. The key + token will be required in pair to operate the API.

Secret

You most likely will not need to use this key in any scenario. The Inbound Now client uses this key to encode and decode data.

Token

The token is used in tandem with the public key to authenticate a connection.

Base API URL

 

The base API URL structure looks like this:

 

http://yoursite.com/inbound-api/v1/

 

API Endpoints

 

The current Leads API contains these endpoints queries

 

  • /leads/ – for retrieving lead profiles
  • /leads/add/ – for creating lead profiles
  • /leads/modify/ – for modifying lead profiles
  • /leads/delete/ – for deleting specific leads
  • /lists/ – for retrieving lead lists
  • /lists/add/ – for adding lead lists
  • /lists/delete/ – for deleting lists
  • /lists/modify/ – for modifying list names
  • /field-map/ – for retrieving mappable fields
  • /analytics/track_link/ – for creating a tracked link that will record click events for specific

 

An example endpoint URL would look like:

 

http://yoursite.com/inbound-api/v1/leads/list_leads/

 

When combining access keys with the base URL a full api request URL looks like:

 

http://yousite.com/inbound-api/v1/leads/list_leads/?key=<API key here>&token=<token here>

 

Response Format

 

The response given by the Inbound API is given in JSON format.

Below is a response given after updating a lead using the /lead/modify endpoint:

 

Paging Parameters

 

By default Inbound API will group lookups in groups of 50.

 

If a query has 100 results then the first 50 will will be returned in the original JSON response, and the next 50 can be accessed by repeating the same call but with &page=2 added onto the request URL or included in the POST data package, for example:

 

http://yoursite.com/inbound-api/v1/leads/?key=<your API key>&token=<token>&page=2

 

You can change the number of results returned per query by using the number parameter. This example will return 100 results per page.

 

http://yoursite.com/inbound-api/v1/leads/?key=<your API key>&token=<token>&results_per_page=100

 

If you would like to retrieve all results at once then set results_per_page to -1 and page to 1

Inbound API Queries

 

In the sections below we will provide information on the types of queries you can perform with the Inbound API. Each query accepts parameters that affects the results returned or the action performed. All queries will require a valid API key and token as an included parameter.

The Inbound API will accept these parameters as GET or POST calls.

1. inbound-api/v1/leads/

Retrieves lead profiles given certain conditions.

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

  • ID – for pulling back a specific profile by id ( INT ,  optional)
  • email – for pulling back a specific profile by email address ( STRING , optional )
  • results_per_page – results returned per page. ( INT , default: 50 , optional )
  • page – page number of resultset to request ( INT, default 1, optional )
  • include_tags – narrows results by tag presence (ARRAY, optional)
  • exclude_tags – narrows results by lack of tag presence (ARRAY, optional)
  • include_lists – narrow results by list participation (ARRAY, optional)
  • exclude_lists – narrow results by lack of list participation. (ARRAY, optional)
  • meta_query – narrow results by custom meta data searches. ( ARRAY based on meta_query in WP_Meta_Query)
  • tax_query – narrow results by custom taxonomy object searches. ( ARRAY, optional, based on tax_query in  WP_Meta_Query)
  • orderby – program how results are sorted. ( MIXED STRING/ARRAY, default ‘date’ , OPTIONAL ,   based on WP_Query’s order_by argument )
  • order – determines ascending or descending order. accepts ASC, DESC ( STRING , default DESC , OPTIONAL )

Example PHP Wrapper & Requests

The code example belows shows a wide variety of ways this endpoint can be used.

https://gist.github.com/atwellpub/ee2403b4f85ca1ef473a

Example JSON Return 

https://gist.github.com/atwellpub/849812720f5eba1f66c0

2. inbound-api/v1/leads/add

Adds a new lead profile into the Leads database.

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

  • meta_data – key/value data pairs to associate with lead ( ARRAY of key pairs REQUIRED )
    • wpleads_email_address ( STRING email address  REQUIRED )
    • wpleads_first_name ( STRING  first name OPTIONAL )
    • wpleads_last_name ( STRING last name OPTIONAL )
    • See here for complete list of Mappable keys
  • lead_lists – array of list ids to associate with lead ( ARRAY lead list IDs  OPTIONAL)
  • tags – array of tags to associate with lead ( ARRAY tags OPTIONAL )

Example PHP Wrapper

The code example belows shows an example of how PHP can be used to send data to the API endpoint /leads/add

https://gist.github.com/atwellpub/c6a1df00912cdbd003a0

Example JSON Return

In event of a successful lead creation event a comprehensive JSON lead object will be returned. If there is a failure an json object with an error message will be returned.

https://gist.github.com/atwellpub/e738f451488480357e37

3. inbound-api/v1/leads/modify

Updates an existing lead profile. Use this endpoint to modify lead meta data, mapped fields, lead list participation, and lead tags.

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

This endpoint requires ID or email to be populated.

  • ID – target lead ID to update (INT )
  • email – target lead email address (STRING )
  • meta_data – key/value data pairs to associate with lead ( ARRAY of key pairs )
    • wpleads_email_address ( STRING email address  OPTIONAL )
    • wpleads_first_name ( STRING  first name OPTIONAL )
    • wpleads_last_name ( STRING last name OPTIONAL )
    • See here for complete list of Mappable keys
  • add_tags – tags to add to the lead ( ARRAY tag names OPTIONAL )
  • remove_tags – tags to remove from a a lead ( ARRAY tag names OPTIONAL )
  • add_to_lists – adds lead to lead lists ( ARRAY lead list ids OPTIONAL )
  • remove_from_lists – remove lead from lead lists ( ARRAY lead list ids OPTIONAL )

Example PHP Wrapper

The code example belows shows an example of how PHP can be used to send data to the API endpoint /leads/modify

https://gist.github.com/atwellpub/52c89d1773714e38c0f7

Example JSON Return

In event of a successful lead modification event a comprehensive JSON lead object will be returned. If there is a failure an json object with an error message will be returned.

https://gist.github.com/atwellpub/854cb23d491089c52bdb

 

4. inbound-api/v1/leads/delete

Comprehensively deletes a lead profile (does not send it to trash).

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

This endpoint requires either an ID param or an email param to be set.

  • ID – target lead ID to delete from leads database  (INT)
  • email – target email to delete from leads database (STRING)

Example PHP Wrapper

The code example belows shows an example of how PHP can be used to send data to the API endpoint /leads/delete

https://gist.github.com/atwellpub/b50e05d6345c2c160e44

Example JSON Return

In event of a successful lead modification event a comprehensive JSON lead object will be returned. If there is a failure an json object with an error message will be returned.

https://gist.github.com/atwellpub/d775c39d819a887bdfe8

 

5. inbound-api/v1/lists

Returns a resultset of list lists ids and labels.

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

This endpoint does not require any additional parameters.

Example JSON Return

https://gist.github.com/atwellpub/9ec8a50383f049a0f850

 

6. inbound-api/v1/lists/add

Adds a lead list to the Leads database. If a lead list by this name is already created then it will return the lead list data.

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

  • name – the name of the list to create ( STRING REQUIRED )
  • description  – the description of the lead list ( STRING OPTIONAL )
  • parent – the lead list id that this list should be categorized under. Leaving this param blank will create a top level lead list (INT OPTIONAL)

Example PHP Wrapper

https://gist.github.com/atwellpub/861877e101b692f5a333

Example JSON Return

https://gist.github.com/atwellpub/78be4f4149baba221976

 

7. inbound-api/v1/lists/delete

Deletes a lead list from the leads database. Does not delete leads belonging to list.

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

  • id – the id of the list to delete ( INT REQUIRED )

Example PHP Wrapper

https://gist.github.com/atwellpub/4883686e16ad2b6732a1

Example JSON Return

https://gist.github.com/atwellpub/2401bff67b9c0adf60ce

 

8. inbound-api/v1/lists/modify

Adds a lead list to the Leads database. If a lead list by this name is already created then it will return the lead list data.

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

  • id – the id of the list to modify( INT REQUIRED )
  • name – the new name of the lead list ( STRING OPTIONAL )
  • description  – the description of the lead list ( STRING OPTIONAL )
  • parent – the lead list id that this list should be categorized under. Leaving this param blank will create a top level lead list (INT OPTIONAL)

Example PHP Wrapper

https://gist.github.com/atwellpub/701e83a709364f7e6b8d

Example JSON Return

https://gist.github.com/atwellpub/f772d41dd90834584ba8

8. inbound-api/v1/field-map

Returns a list of mappable lead fields with their labels.

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

No parameters are required for this endpoint.

Example PHP Wrapper

https://gist.github.com/atwellpub/aad82fd32afea93de002

Example JSON Return

https://gist.github.com/atwellpub/6bbd5eef28c387316310

 

9. inbound-api/v1/analytics/track-link

Creates a link redirect that helps developers track lead link clicks/

Required Authorization Parameters

  • key – api key generated by user (STRING)
  • token – api access token generated by user (STRING)

Accepted Parameters

In order to track a lead’s click we will need to populate at least one of the following params: id, email.

 

  • id – the lead id to associate the tracked link with ( INT OPTIONAL-R )
  • email – the lead email to associate the tracked link with ( STRING OPTIONAL-R )
  • url – the URL to send the lead to ( STRING REQUIRED )
  • tracking_id – campaign identification string. (STRING REQUIRED)
  • add_lists – array of list ids to associate with lead when clicked ( ARRAY lead list IDs  OPTIONAL)
  • remove_lists – array of list ids to disassociate lead from when link is clicked ( ARRAY lead list IDs  OPTIONAL)
  • add_tags – array of tags to associate with lead ( ARRAY tags OPTIONAL )
  • remove_tags – array of tags to dissassociate lead from when link is clicked  ( ARRAY tags OPTIONAL )
  • custom_data – key/value data pairs for use in custom development situations ( ARRAY of key/value pairs OPTIONAL)

Example PHP Wrapper

https://gist.github.com/atwellpub/549edf346b7926024e8c

Example JSON Return

 

Bonus PHP Examples:

  1. Gets 300 random leads matching a certain condition and adds a tag to these leads: https://gist.github.com/atwellpub/f04c43b27865605bc74c