Lead Gen & CRM's API allows your application to connect to the internal CRM functionality of Lead Gen & CRM.
This article will provide an overview of the Lead Gen & CRM API.
Article Contents
Trial | ||
Essential | ||
Advanced | ✓ | |
Ultimate | ✓ |
Administrators | ✓ | |
Company Managers | ||
Marketing Managers | ||
Sales Managers | ||
Salespersons | ||
Jr. Salespersons |
Additional API Information
This article provides a general overview of Lead Gen & CRM's API. However, given the size and scope of the API, information is broken up and is contained in different articles. Each article focuses on a specific function of Lead Gen & CRM's API. Additional API information can be found in the following articles:
Lead Gen & CRM's API and Usage Limitations
Lead Gen & CRM's current API implementation involves many features, such as:
|
Note: When using the API to update a lead field, that value will always overwrite any existing field value and will not be added in addition to it.
|
Each Lead Gen & CRM partner is currently allotted 50,000 API requests per day by default, with a maximum of 10 queries per second and a limit of 500 queries per request. On average, users can add around 1 million contacts per day. However, requests may be rate-limited in times of high traffic and by volume of lead information. Be aware that the amount of API requests is subject to change in the future.
Generating API Keys
In order to access the Lead Gen & CRM API, you must generate both an account ID and an API key. The Lead Gen & CRM API currently does not support sessions, so these keys must be supplied during each request.
To access Lead Gen & CRM's API and create API keys, do the following:
|
Note: Constant Contact offers Professional Services to assist with Lead Gen & CRM API issues.
|
Accessing API References
To access example code, methods, schema and error codes, do the following:
- Click Settings in the left toolbar.
- Click API Reference, located under Lead Gen & CRM API in the left panel.
- Click the Example Code tab for access to example codes.
- Click the Methods tab for method information.
- Click the Schema tab for schema information.
- Click the Error Codes tab for a list of error codes.
Using the Lead Gen & CRM API
Using the Lead Gen & CRM API to update a field value will always overwrite any existing field value. The overwrite will occur instead of appending to, adding to, or modifying the value in any other manner.
When you create a custom field, Lead Gen & CRM generates a system name, which is what you use in the API. However, if the name of the field is later changed, the system name will not change. This is to prevent accidentally breaking an API connection by changing a label.
For example, if a custom field is called Favorite Color
, the system name may be Favorite_Color_5a0dd86e6e290
. If the custom field is later changed Pet's Name
in the UI, it will still be Favorite_Color_5a0dd86e6e290
in the API. At this point, it would be best to create a new field to avoid confusion.
Request and Response Format
Once your keys have been generated, you can begin creating the mechanism to retrieve and post data to and from the Lead Gen & CRM application. All requests are made using an HTTPs POST encoded in JSON. Lead Gen & CRM uses a standard very similar to JSON-RPC for request handling.
API Requests
Requests must be made to the following URL:
https://api.sharpspring.com/pubapi/v1/
Version | Description | |||
|
v1 |
https://api.sharpspring.com/pubapi/v1/ |
|
|
|
v1.2 |
https://api.sharpspring.com/pubapi/v1.2/ |
|
API Authentication
Authentication parameters must be appended to the URL as query strings:
accountID={account-id-here}&secretKey={secret-key-here}
Each request must contain the following three fields:
Field | Description | |||
Method |
The name of the API method being called. |
|
||
Params |
A parameters hash to be passed to the method. |
|
||
ID |
A user-supplied request ID for correlating requests. |
|
API Responses
Each API response contains the following three fields:
Field | Description | |||
Result |
The return value of the method called. Usually a list of Objects and Object-level errors. |
|||
Error |
An API-level error returned by the API. |
|||
ID |
A user-supplied request ID for correlating requests. |
The following is an example of using the getLead
method to retrieve a single lead by its ID:
"Request Data:" { "method":"getLead", "params":{ "id":"<a lead id>" }, "id":"<your request ID>", } "Response Data:" { "result":{ "lead":[ { "id":"<id>", "companyName":"<company name>", "title":"<title>", "firstName":"<first name>", "lastName":"<last name>", "street":"<street>", "city":"<city>", "country":"<country>", "state":"<state>", "zipcode":"<zip code>", "emailAddress":"<email>", "website":"<website>", "phoneNumber":"<phone number>", "mobilePhoneNumber":"<mobile phone number>", "faxNumber":"<fax number>", "description":"<description>", "leadScore":"<lead score>", "industry":"<industry>", "active":"<is active>", "isUnsubscribed":"<is unsubscribed>", "leadStatus":"<lead status>" } ] }, "error":null, "id":"<your request ID>" }
API-Level Errors
When an invalid request is made to the API, an error object will be returned.
An example API-level error object is as follows:
{ "result":null, "error":{ "code":205, "message":"Invalid parameters", "data":{ "params":[ { "param":"id", "message":"Expected data of type integer", "validFormat":{ "type":"int", "length":11, "required":false } } ] } }, "id":"<request ID>" }
Object-Level Errors
When an invalid-format object is passed as part of a list (such as in a create or update query), an object-level error will be returned in the result array. Since the error was at the object level, no API errors will be returned.
An example object-level error object is as follows:
{ "result":{ "creates":[ { "success":"false", "error":{ "code":301, "message":"Entry already exists", "data":[] } } ] }, "error":null, "id":"<request ID>" }
502 Errors and Expect:100-Continue
If you experience a 502 error when running a call, check to see if Expect:100-continue
is enabled in the header. Lead Gen & CRM uses Google's GCE service, and when the Expect:100-continue
header is enabled, API calls longer than 1,024 characters (including the secret key and other data) will result in a 502 error. This option is on by default in .NET, as well as in .PHP.
Disabling Expect:100-Continue for .NET
To disable Expect:100-continue
in .NET, run the following lines prior to the API call:
System.Net.ServicePointManager.Expect100Continue: false;
rqst.ServicePoint.Expect100Continue = false;
Disabling Expect:100-Continue for .PHP
To disable Expect:100-continue
in Curl within .PHP, add the Expect option with no value to the HTTPHEADER
section.
The last line in the below example shows how to disable Expect:100-continue
in .PHP with this method:
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data),
'Expect: '
));