Understanding Lead Gen & CRM Open API: Overview

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

• Additional API Information
• Lead Gen & CRM's API and Usage Limitations
• Generating API Keys
• Accessing API References
• Using the Lead Gen & CRM API
• Request and Response Format
• API-Level Errors
• Object-Level Errors
• 502 Errors and Expect:100-Continue

Available With:

Trial
Essential
Advanced	✓
Ultimate	✓

Toolbar:

Settings

Users:

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

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:

Accessing API References

To access example code, methods, schema and error codes, do the following:

1. Click  Settings in the left toolbar.
2. Click API Reference, located under Lead Gen & CRM API in the left panel.
3. Click the Example Code tab for access to example codes.
4. Click the Methods tab for method information.
5. Click the Schema tab for schema information.
6. 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/

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:

API Responses

Each API response contains the following three fields:

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: '
));