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

ParameterRequired?DescriptionSQL DatatypeExample
keyREQUIREDeLocal API Key provided to you by eLocal. This key identifies the request as coming from your service.varchar(20)afdf398faedfa3
zip_codeREQUIREDA 5-digit US ZIP Code or a 7-character Canada Postal Code for the lead.varchar(7)01233 M4C 1A1
need_idREQUIREDWhen 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_consentREQUIREDHas the user given consent compliant with the (Telephone Consumer Protection Act) that they may be contacted by auto-dialers. More details on (TCPA Requirements). If not specified, this is assumed to be false.booleanfalse
phoneOPTIONALYou can choose to send us this value if you would like us to check for duplicates.varchar123-456-7890
emailOPTIONALYou can choose to send us this value if you would like us to check for duplicates.varcharexample@email.com
sender_idOPTIONALYOUR 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_keyOPTIONALSome 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
exclusiveOPTIONALIf shared leads are being sent to eLocal, this flag should be set to _false_.
If not specified the flag is defaulted to true
booleantrue
slots_availableREQUIRED 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.integer3
leadid_identifierOPTIONALA string that uniquely identifies the Jornaya lead id relevant to this lead.varchar
trusted_form_cert_idOPTIONALA string that uniquely identifies the TrustedForm certificate relevant to this lead.text
web_lead_source_urlREQUIREDThe website url where the consumer submitted the lead form.varchar(255)https://my-domain/lead-request-submission-page

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

ParameterRequired?DescriptionSQL DatatypeExample
statusREQUIREDDenotes whether the request was successful or an error.varchar(7)
success
The request was processed successfully.
failure
The request was processed but there is no interest.
error
The request was NOT processed and no ping was recorded.
tokenREQUIREDAn eLocal generated token for the request. Used to uniquely identify request when debugging.varchar(50)2S2S-A2SD-K48B
messageOPTIONALAny additional message information about this request. If an error occurs, details will be contained in this message.textAPI Key is invalid
sender_idOPTIONALYOUR 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
priceOPTIONALIf 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.decimal5.55
exclusiveOPTIONALIf 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.booleantrue
slots_claimedREQUIRED 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.integer3
hashed_contactsOPTIONAL Only used with shared leads. Only shows up if slots claimedAn 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"}}

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

ParameterRequired?DescriptionSQL DatatypeExample
keyREQUIREDeLocal API Key provided to you by eLocal. This key identifies the request as coming from your service.varchar(20)afdf398faedfa3
ping_tokenREQUIRED if a ping request was made for this post. Should not be present if a direct (i.e. pingless) postThe 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_codeREQUIREDA 5-digit US ZIP Code or a 7-character Canada Postal Code for the lead.varchar(7)01233 M4C 1A1
need_idREQUIREDWhen 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_nameREQUIREDThe first name of the person asking for the lead.varchar(255)Lester
last_nameOPTIONALThe last name of the person asking for the lead. While optional, including this field is strongly recommended.varchar(255)Tester
phoneREQUIREDThe 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_consentREQUIREDHas the user given consent compliant with the (Telephone Consumer Protection Act) that they may be contacted by auto-dialers. More details on (TCPA Requirements). If not specified, this is assumed to be false.booleanfalse
trusted_form_cert_idREQUIREDA string that uniquely identifies the TrustedForm certificate relevant to this lead. Either trustedForm certificate id (trusted_form_cert_id) or Jornaya Lead id(leadid_identifier) is required.text
emailOPTIONALThe primary contact email for the person asking for the lead.varchar(255)exampleemail@gmail.com
addressOPTIONALThe 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 .text123 Main St
descriptionOPTIONALAny additional information about the lead that a provider should know about. Generally, this text should be unstructured.text
sender_idOPTIONALYOUR 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_keyOPTIONALSome 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
exclusiveOPTIONALIf this lead is a shared lead, this flag should be set to _false_.
If not specified the flag is defaulted to true
booleantrue
hashed_contactsOPTIONAL Only used with shared leadsAn 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_identifierREQUIREDA string that uniquely identifies the Jornaya lead id relevant to this lead. Either trustedForm certificate id (trusted_form_cert_id) or Jornaya Lead id(leadid_identifier) is required.varchar
questionsOPTIONALA set of questions and answers that the consumer has previously answered.array of objects"questions": [{ "question_text": "Existing customer?", "answer text": "No" }, { "question_text": "commercial?", "answer_text": "No" }]
query_stringOPTIONALThe full querystring (usually used for tracking).varchar(255)?key_1=vlue_1&key2=value_2
web_lead_source_urlREQUIREDThe website url where the consumer submitted the lead form.varchar(255)https://my-domain/lead-request-submission-page

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

ParameterRequired?DescriptionSQL DatatypeExample
statusREQUIREDDenotes whether the request was successful or an error.varchar(7)
success
The request was processed successfully.
failure
The request was processed but a post could not be created.
error
The request was NOT processed and no post was recorded.
tokenREQUIREDAn eLocal generated token for the request. Used to uniquely identify request when debugging.varchar(50)2S2S-A2SD-K48B
messageOPTIONALAny additional message information about this request. If an error occurs, details will be contained in this message.textAPI Key is invalid
elocal_lead_idOPTIONALThe eLocal internal identifier for the lead generated from this request. This will only be present on a successful transaction.integer9876
sender_idOPTIONALYOUR 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
exclusiveOPTIONALIf 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.booleantrue
slots_availableREQUIRED 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.integer3
hashed_contactsOPTIONAL Only used with shared leadsAn 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",
        "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

ParameterRequired?DescriptionSQL DatatypeExample
keyREQUIREDeLocal API Key provided to you by eLocal. This key identifies the request as coming from your service.varchar(20)afdf398faedfa3
tokenREQUIREDThe token that came from the ping request associated with this bid.varchar(50)2S2S-A2SD-K48B
winning_bidREQUIREDBid price for the winning bid for this ping. Number should be greater or equal to 0decimal60.00

Complete Response

JSON Format

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

Response Details

ParameterRequired?DescriptionSQL DatatypeExample
statusREQUIREDDenotes whether the request was successful or an error.varchar(7)success or error
tokenREQUIREDAn eLocal generated token for the request. Used to uniquely identify request when debugging.varchar(50)2S2S-A2SD-K48B
messageOPTIONALAny additional message information about this request. If an error occurs, details will be contained in this message.textAPI 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"}}