API Interface

The REST-style API can be used to POST leads directly to your channelLEADS install, either directly from your website forms (the "Direct Post" mode) or in “API mode” via HTTP POST from a program on your server (the “API client”). The only differences between the 2 modes are

• in Direct Post mode, the response sent back by channelLEADS is human-readable HTML, while in API mode the response is an xml string that's easier for your program to understand.
• to use API mode, you must include the field apiFlag with value 1. If the apiFlag is not seen, Direct Post mode will be assumed

API mode accepts HTTP POST (actually, https since the API endpoint is a secure https url) with form-encoded field data (i.e. the same format a browser uses). All fields are as described in the Direct Post documentation. The response will be an xml document with status info, error codes when needed, and the lead ID which could be used to construct a link to the lead details in the LEADpiper system.

See below for an example.

1. setup a direct form form scheme using the Leads→Sources & Schemes setup area.
2. set up form data using Direct Post field names
   • don't forget to include the “directPostKey” field and to set “apiFlag” to 1
   • it is not necessary to include the “comments” spam trap field or the “thankYouUrl” field
3. test by POSTing to the API endpoint http://your channelLEADS install/API/Leads/v2/ and make sure you can parse both success and non-success responses as described below
4. start using your API

You can test API mode using the popular Curl command line http client. In this example, we're posting a lead w/ standard fields “email” and “company” and custom fields “company_size” and “industry”

curl -d directPostKey="OSBD NUSS EXBO 96IR&email=frankdunn@gmail.com&x-company_size=33&apiFlag=1&company=roxy&x-industry='civil engineering'" http://[your channelLEADS install URL]/API/Leads/

since we specified apiFlag=1, the response comes back as xml and looks like this:

<response>
  <result>1</result>
  <leadId>1636</leadId>
</response>

The following are possible return values based on what is submitted:

• For a successful entry where leadId is the primary key of the lead that was just created:

<response>
  <result>1</result>
  <leadId>2133</leadId>
</response>

• If the <directPostKey> hidden field is not set, an error is returned:

<response>
  <result>0</result>
  <message>Authentication failed. Authentication key not set.</message>
</response>

• If the <directPostKey> hidden field is set but incorrect (check your <directPostKey> value through the Leads→Sources & Schemes setup page in your channelLEADS account), the following error is returned:

<response>
  <result>0</result>
  <message>Authentication failed.  Incorrect authentication key.</message>
</response>

• If the Contact name is blank, the following error is returned:

<response>
  <result>0</result>
  <message>Contact is a required field.</message>
</response>

• If the E-mail address is left blank, the following error is returned:

<response>
  <result>0</result>
  <message>Email address is a required field.</message>
</response>