Introduction
The eLocal Ping/Post API allows eLocal partners to conditionally send a subset of lead information to eLocal's systems to query whether eLocal is interested in buying the full lead. This subset request is known as the PING. If eLocal expresses interest, the full lead data is then sent to eLocal. Sending the full lead information is referred to as the POST.
This document defines the interface for both the ping and the post methods.
About the eLocal API
Technical Requirements for all Requests
- All requests will use JSON notation to communicate data
- All requests must be made with a content type of application/json
- All requests must be made using an HTTPS POST request
Development/Testing
For your integration, eLocal will supply you with an API key. Initially, your account will be marked as "in development". You will be able to make sample requests against a testing service and validate that requests and responses are working as expected. While in development, no leads posted to the server will be delivered to eLocal clients. All requests with the developer key should be made on http://api.elocal.com/
There are two main goals during development:
- The eLocal partner develops the code to integrate with the API
- The eLocal partner and eLocal work together to develop a set of partner-specific Need IDs that classify each request. This mapping will provide a data crosswalk between the partner's classifications and eLocal's classifications.
Production
When development is complete and all data has been mapped to Need IDs, eLocal will move your account to production mode.
Exclusive vs. Shared Leads
When integrating with eLocal we support two different methods of sending leads.
Exclusive Leads
When eLocal is buying leads exclusively, no one besides eLocal will be contacting providers with this lead. Exclusive leads are the most common way eLocal integrates with partners. It is assumed that a ping/post will be exclusive, unless the exclusive flag is explicitly set to false.
Shared Leads
On occasion, eLocal will received shared leads from their partners. These are leads that may have been sent to providers either by our partner, or by other organization collaborating with the partner. When working with shared leads, some additional information will need to be sent between the partner and eLocal.
- When pinging eLocal, the partner will need to explicitly tell eLocal that the lead will be shared and how many slots will be available
- When eLocal is interested in the shared lead, the response will include the number of slots eLocal is interested in purchasing. This number will be greater than zero and less than or equal to the number of slots available.
- Upon posting to eLocal, the partner will again need to explicitly tell eLocal that the lead will be shared and how many slots will be available. In addition the partner will need to inform eLocal about where the lead has already sent. This is done by sending over hashes that represent the phone numbers and/or email addresses that the lead has been sent to. There may be 0 to n hashes sent over with the post request.
- eLocal will respond to the shared lead post with the number of slots that were taken as well as a list of 1 to n hashes that represent the phone numbers and/or email addresses that eLocal contacted with the lead.
Hashes for Contact Information
When a lead is exclusively sold to eLocal, it is easy to ensure that no vendor receives the same leads multiple times. However, with shared leads, it becomes more challenging to make sure there is no duplication. There is a competing need to not be sending plain text emails and phone numbers over this communication channel; we want to minimize the risk of any accidental leakage of this data. To allow for de-duplication while not sending over the plain text information, we will hash all communication values (emails and phones) that are being contacted using SHA1 and transmit the hexadecimal representation of the hash.
For example, if I were sending a lead to joe@gmail.com, the resulting hash would be 845336aee473fced1a585b0bef609c887b29c1bc.
Dynamic Pricing Information
The eLocal API has the ability to return information about what price we are willing to pay. When a ping request is made is accepted by eLocal, we will return the price at which we are willing pay for this lead in the price field.
When constructing your post request JSON, please make sure that the ping_token field is filled in with the ping_token. This will ensure that the pricing information returned to you in the ping will be used for the post.
Ping
The ping is sent to eLocal by the lead provider. It provides enough information about the lead to allow eLocal to decide whether they would like to buy the full lead or not. Generally, we will require information about the lead (called the need_id) and the geography (through the zip code) to determine whether we would like to accept the lead
Ping Request
URL Path
/lead/ping
JSON Format
{"ping": {
"key": "[value]",
"zip_code": "[value]",
"need_id": "[value]",
"tcpa_consent": "true|false",
"sender_id": "[value]",
"sender_origin_key": "[value]",
"exclusive": "[value]",
"slots_available": "[value]",
"leadid_identifier": "[value]",
}
}
Request Details
| Parameter | Required? | Description | SQL Datatype | Example |
|---|---|---|---|---|
| key | REQUIRED | eLocal API Key provided to you by eLocal. This key identifies the request as coming from your service. | varchar(20) | afdf398faedfa3 |
| zip_code | REQUIRED | A 5-digit US ZIP Code or a 7-character Canada Postal Code for the lead. | varchar(7) | 01233 M4C 1A1 |
| need_id | REQUIRED | When integrating with a partner, eLocal will work with you to to determine your set of need IDs. These need IDs map to specific details of the lead so we can ensure we have a provider to accept the lead. Often these are your own identifiers. | varchar(255) | 9876 |
| tcpa_consent | REQUIRED | Has the user given consent compliant with the [Telephone Consumer Protection Act](http://en.wikipedia.org/wiki/Telephone_Consumer_Protection_Act_of_1991) that they may be contacted by auto-dialers. More details on [TCPA Requirements](http://www.kleinmoynihan.com/publication/new-tcpa-rules-effective-october-16-2013/). If not specified, this is assumed to be false. | boolean | false |
| sender_id | OPTIONAL | YOUR identifier for this request. This is entirely optional, but if specified, it will be echoed back to you in the response. | varchar(255) | 9876 |
| sender_origin_key | OPTIONAL | Some partners. This optional field gives eLocal information about the origin for the lead. It is intended to differentiate source information for leads when the integrating partner sources their own leads from multiple providers. It is entirely optional, but useful for eLocal Quality Control. | varchar(255) | abc-123 |
| exclusive | OPTIONAL |
If shared leads are being sent to eLocal, this flag should be set to _false_.
If not specified the flag is defaulted to true |
boolean | true |
| slots_available | REQUIRED if exclusive set to false. Otherwise ignored. | A positive integer reflecting the number of shared slots available for eLocal to send leads to. This field is required if a lead is not exclusive. | integer | 3 |
| leadid_identifier | OPTIONAL | A [Lead ID](http://www.leadid.com) Identifier used to uniquely identify the lead. | varchar | |
| phone | OPTIONAL | You can choose to send us this value if you would like us to check for duplicates. | varchar | 123-456-7890 |
| OPTIONAL | You can choose to send us this value if you would like us to check for duplicates. | varchar | example@email.com | |
| certificate_type | OPTIONAL | This optional but highly recommended parameter informs us whether the lead has a Trusted Form Certificate which will be provided at POST time. Currently supported values are 'Trusted Form' and 'None'. Providing this parameter improves your chances of selling your lead to us. | varchar | Trusted Form |
Ping Response
JSON Format
{"response": {
"status": "success|error|failure",
"token": "[value]",
"sender_id": "[value]",
"message": "[value]",
"exclusive": true|false,
"slots_claimed": 1-5,
"price": 5.55,
"hashed_contacts": [
"[value]",
"[value]"
]
}
}}
Response Details
| Parameter | Required? | Description | SQL Datatype | Example |
|---|---|---|---|---|
| status | REQUIRED | Denotes whether the request was successful or an error. | varchar(7) |
|
| token | REQUIRED | An eLocal generated token for the request. Used to uniquely identify request when debugging. | varchar(50) | 2S2S-A2SD-K48B |
| message | OPTIONAL | Any additional message information about this request. If an error occurs, details will be contained in this message. | text | API Key is invalid |
| sender_id | OPTIONAL | YOUR identifier for this request. This is entirely optional, but if specified it the request, it will be echoed back to you in the response. | varchar(255) | 9876 |
| price | OPTIONAL | If this is an exclusive lead, eLocal will return the price we are willing to pay for the lead. If this is a shared lead, it will be the price per shared slot. | decimal | 5.55 |
| exclusive | OPTIONAL | If this parameter is passed in during a ping request, it's value will be echoed back in the response. If not passed in, this is assumed to be true. | boolean | true |
| slots_claimed | REQUIRED if exclusive set to false. | A positive integer reflecting the number of shared slots eLocal would be interested in sending this lead to. This value will only appear if the exclusive flag is set to false. | integer | 3 |
| hashed_contacts | OPTIONAL Only used with shared leads. Only shows up if slots claimed | An array of strings that are hexadecimal representations of email/phone numbers that have been contacted with this lead by eLocal. Used to make sure there is no duplication of leads being sent. | array of strings | ["5131512f2d165ca283b055bc6f32bc01dd23121e"] |
Example Request/Response
Using curl
Success
> curl -H 'Content-type: application/json' \
-d '{"ping": {"zip_code":"19428", "need_id": "1000", "key":"YOUR_KEY_HERE" }}' \
https://api.elocal.com/lead/ping
{"response":{"status":"success","token":"ximok-hesok-dovix"}}
Success for non-exclusive lead
> curl -H 'Content-type: application/json' \
-d '{"ping": {"zip_code":"19428", "need_id": "1000", "key":"YOUR_KEY_HERE", "exclusive": false, "slots_available": 3 }}' \
https://api.elocal.com/lead/ping
{"response":{"status":"success","token":"ximok-hesok-dovix", "exclusive":false, "slots_claimed": 2}}
Failure
> curl -H 'Content-type: application/json' \
-d '{"ping": {"zip_code":"99556", "need_id": "1000", "key":"YOUR_KEY_HERE" }}' \
https://api.elocal.com/lead/ping
{"response":{"status":"failure","token":"xinaf-lutif-cosyx",
"message":"Not interested in this lead"}}
Post
TrustedForm Certificate
All posts require a TrustedForm certificate. The certificate is generated by including the following script on any page containing a form. This script will add a hidden field containing the certificate to the form.
<!-- Generate a TrustedForm Certificate -->
<script type="text/javascript">
(function() {
var field = 'xxTrustedFormCertUrl';
var provideReferrer = false;
var tf = document.createElement('script');
tf.type = 'text/javascript'; tf.async = true;
tf.src = 'http' + ('https:' == document.location.protocol ? 's' : '') +
'://api.trustedform.com/trustedform.js?provide_referrer=' + escape(provideReferrer) + '&field=' + escape(field) + '&l='+new Date().getTime()+Math.random();
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(tf, s); }
)();
URL Path
/lead/post
JSON Format
{"post": {
"key": "[value]",
"ping_token": "[value]",
"zip_code": "[value]",
"need_id": "[value]",
"tcpa_consent": true|false,
"sender_id": "[value]",
"sender_origin_key": "[value]",
"first_name": "[value]",
"last_name": "[value]",
"phone": "[value]",
"email": "[value]",
"address": "[value]",
"description": "[value]",
"exclusive": true|false,
"slots_available": "[value]",
"trusted_form_cert_id": "[value]",
"hashed_contacts": [
"[value]",
"[value]"
],
"leadid_identifier": "[value]"
}
}
Request Details
| Parameter | Required? | Description | SQL Datatype | Example |
|---|---|---|---|---|
| key | REQUIRED | eLocal API Key provided to you by eLocal. This key identifies the request as coming from your service. | varchar(20) | afdf398faedfa3 |
| ping_token | REQUIRED if a ping request was made for this post. Should not be present if a direct (i.e. pingless) post | The token that came from the ping request associated with this post. For partners that are directly posting to eLocal, this field may be ignored. | varchar(50) | 2S2S-A2SD-K48B |
| zip_code | REQUIRED | A 5-digit US ZIP Code or a 7-character Canada Postal Code for the lead. | varchar(7) | 01233 M4C 1A1 |
| need_id | REQUIRED | When integrating with a partner, eLocal will work with you to to determine your set of need IDs. These need IDs map to specific details of the lead so we can ensure we have a provider to accept the lead. Often these are your own identifiers. | varchar(255) | 9876 |
| first_name | REQUIRED | The first name of the person asking for the lead. | varchar(255) | Lester |
| last_name | OPTIONAL | The last name of the person asking for the lead. While optional, including this field is strongly recommended. | varchar(255) | Tester |
| phone | REQUIRED | The primary contact phone number for the person asking for the lead. Phone numbers should be formatted with 10 digits, optionally with hyphens. | varchar(12) | 555-555-5555 |
| tcpa_consent | REQUIRED | Has the user given consent compliant with the [Telephone Consumer Protection Act](http://en.wikipedia.org/wiki/Telephone_Consumer_Protection_Act_of_1991) that they may be contacted by auto-dialers. More details on [TCPA Requirements](http://www.kleinmoynihan.com/publication/new-tcpa-rules-effective-october-16-2013/). If not specified, this is assumed to be false. | boolean | false |
| trusted_form_cert_id | REQUIRED | A string that uniquely identifies the TrustedForm certificate relevant to this lead. | text | |
| OPTIONAL | The primary contact email for the person asking for the lead. | varchar(255) | exampleemail@gmail.com | |
| address | OPTIONAL | The address for the person asking for the lead. This may include street address information, but city and state are not needed as we derive the city and state from the zip code . | text | 123 Main St |
| description | OPTIONAL | Any additional information about the lead that a provider should know about. Generally, this text should be unstructured. | text | |
| sender_id | OPTIONAL | YOUR identifier for this request. This is entirely optional, but if specified, it will be echoed back to you in the response. | varchar(255) | 9876 |
| sender_origin_key | OPTIONAL | Some partners. This optional field gives eLocal information about the origin for the lead. It is intended to differentiate source information for leads when the integrating partner sources their own leads from multiple providers. It is entirely optional, but useful for eLocal Quality Control. | varchar(255) | abc-123 |
| exclusive | OPTIONAL |
If this lead is a shared lead, this flag should be set to _false_.
If not specified the flag is defaulted to true |
boolean | true |
| hashed_contacts | OPTIONAL Only used with shared leads | An array of strings that are hexadecimal representations of email/phone numbers that have already been contacted with this lead. Used to make sure there is no duplication of leads being sent. | array of strings | ["5131512f2d165ca283b055bc6f32bc01dd23121e"] |
| leadid_identifier | OPTIONAL | A [Lead ID](http://www.leadid.com) Identifier used to uniquely identify the lead. | varchar |
Post Response
JSON Format
{"response": {
"status": "success|error|failure",
"token": "[value]",
"sender_id": "[value]",
"sender_origin_key": "[value]",
"elocal_lead_id": "[value]",
"message": "[value]"}
}
Response Details
| Parameter | Required? | Description | SQL Datatype | Example |
|---|---|---|---|---|
| status | REQUIRED | Denotes whether the request was successful or an error. | varchar(7) |
|
| token | REQUIRED | An eLocal generated token for the request. Used to uniquely identify request when debugging. | varchar(50) | 2S2S-A2SD-K48B |
| message | OPTIONAL | Any additional message information about this request. If an error occurs, details will be contained in this message. | text | API Key is invalid |
| elocal_lead_id | OPTIONAL | The eLocal internal identifier for the lead generated from this request. This will only be present on a successful transaction. | integer | 9876 |
| sender_id | OPTIONAL | YOUR identifier for this request. This is entirely optional, but if specified it the request, it will be echoed back to you in the response. | varchar(255) | 9876 |
| exclusive | OPTIONAL | If this parameter is passed in during a post request, it's value will be echoed back in the response. If not passed in, this is assumed to be true. | boolean | true |
| slots_available | REQUIRED if exclusive set to false. | An integer greater than or equal to zero reflecting the number of shared slots eLocal will be taking for this lead. This value will only appear if the exclusive flag is set to false. | integer | 3 |
| hashed_contacts | OPTIONAL Only used with shared leads | An array of strings that are hexadecimal representations of email/phone numbers that have been contacted with this lead by eLocal. Used to make sure there is no duplication of leads being sent. | array of strings | ["5131512f2d165ca283b055bc6f32bc01dd23121e"] |
Example Request/Response
Using curl
Success
curl -H 'Content-type: application/json' \
-d '{"post": {"zip_code":"19428", "need_id": "1000", "key":"YOUR_KEY_HERE", "first_name": "Lester", "last_name": "Tester", "phone": "555-555-5555", "email": "lester@tester.com" }}'\
https://api.elocal.com/lead/post
{"response":{"status":"success","token":"ximof-cosyf-lysyx","elocal_lead_id":1154763}}%
Success / Shared Request
curl -H 'Content-type: application/json' \
-d '{"post": {"zip_code":"19428", "need_id": "1000", "key":"YOUR_KEY_HERE", "first_name": "Lester", "last_name": "Tester", "phone": "555-555-5555", "email": "lester@tester.com" }}'\
https://api.elocal.com/lead/post
{"response":{"status":"success","token":"ximof-cosyf-lysyx","elocal_lead_id":1154763}}%
Failure
curl -H 'Content-type: application/json' \
-d '{"post": {"zip_code":"19428", "need_id": "1000", "key":"YOUR_KEY_HERE", "first_name": "Lester", "last_name": "Tester", "phone": "", "email": "lester@tester.com" }}'\
https://api.elocal.com/lead/post
{"response":{"status":"failure","token":"ximef-misuk-casex","message":"Could not save lead: Phone is required"}}
Final Pricing
The final_pricing callback is an optional callback that you can send to eLocal to let us know what the ping was sold for. This is helpful for us to refine our bids and increase payouts.
The callback requires the token we returned on our ping and the winning bid's price.
URL Path
/lead/final_pricing
JSON Format
{"final_pricing": {
"key": "[value]",
"token": "[value]",
"winning_bid": "[value]"
}
}
Request Details
| Parameter | Required? | Description | SQL Datatype | Example |
|---|---|---|---|---|
| key | REQUIRED | eLocal API Key provided to you by eLocal. This key identifies the request as coming from your service. | varchar(20) | afdf398faedfa3 |
| token | REQUIRED | The token that came from the ping request associated with this bid. | varchar(50) | 2S2S-A2SD-K48B |
| winning_bid | REQUIRED | Bid price for the winning bid for this ping. Number should be greater or equal to 0 | decimal | 60.00 |
Complete Response
JSON Format
{
"response": {
"status": "success|error",
"token": "[value]",
"message": "[value]"
}
}
Response Details
| Parameter | Required? | Description | SQL Datatype | Example |
|---|---|---|---|---|
| status | REQUIRED | Denotes whether the request was successful or an error. | varchar(7) | success or error |
| token | REQUIRED | An eLocal generated token for the request. Used to uniquely identify request when debugging. | varchar(50) | 2S2S-A2SD-K48B |
| message | OPTIONAL | Any additional message information about this request. If an error occurs, details will be contained in this message. | text | API Key is invalid |
Example Request/Response
Using curl
Success
> curl -H 'Content-type: application/json' \
-d '{"final_pricing": {"token":"2S2S-A2SD-K48B", "winning_bid": 65, "key":"YOUR_KEY_HERE" }}' \
https://api.elocal.com/lead/final_pricing
{"response":{"status":"success", "token":"ximok-hesok-dovix"}}
Failure
> curl -H 'Content-type: application/json' \
-d '{"final_pricing": {"token":"2S2S-A2SD-K48B", "winning_bid": 65, "key":"YOUR_KEY_HERE" }}' \
https://api.elocal.com/lead/final_pricing
{"response":{"status":"error", "token":"ximok-hesok-dovix", "message": "Problem retrieving lead information"}}