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 thePING. 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 https://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 be845336aee473fced1a585b0bef609c887b29c1bc.

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 pricefield.

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.

Web Form Lead 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

https://api.elocal.com/lead/ping

JSON Format

{"ping": 
  {
    "key": "[value]",
    "zip_code": "[value]",
    "need_id": "[value]",
    "tcpa_consent": "[true|false]",
    "sender_id": "[value]",
    "sender_origin_key": "[value]",
    "phone": "[value]",
    "email": "[value]",
    "exclusive": "[true|false]",
    "slots_available": "[value]",
    "certificate_type": "[Trusted Form|None]",
    "leadid_identifier": "[value]",
    "trusted_form_cert_id": "[value]",
    "web_lead_source_url": "[value]"
  }
}

Request Details

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

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"}}

Web Form Lead Post

URL Path

https://api.elocal.com/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]",
    "questions": [
      {
        "question_text": "question-1",
        "answer_text": "answer-1"
      },
      {
        "question_text": "question-2",
        "answer_text": "answer-2"
      },
      {
        "question_text": "question-3",
        "answer_text": "answer -3"
      }
    ],
    "query_string": "[value]",
    "web_lead_source_url": "[value]"
  }
}

Request Details

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

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",
        "questions": [
          {
            "question_text": "Existing customer?",
            "answer text": "No"
          },
          {
            "question_text": "commercial?",
            "answer_text": "No"
          }
        ]}}'\\ 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"}}

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) + '&amp;field=' + escape(field) + '&amp;l='+new Date().getTime()+Math.random();
      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(tf, s); 
    })();
  </script>
  <p>
    <noscript>
      <img src="http://api.trustedform.com/ns.gif" />
    </noscript>
  </p>

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

Complete Response

JSON Format

{
  "response": {
    "status": "success|error",
    "token": "[value]",
    "message": "[value]"
  }
}

Response Details

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"}}