eLocal Call Ping API

Introduction

The eLocal Call Ping API allows partners to query purchase interest in real-time by sending a subset of call information to eLocal's systems. This subset request is known as the 'ping'. When the eLocal system signals purchase intent, it will issue a response indicating a bid price for the call, as well as the phone number to which the call should be routed upon sale. A callback reporting method ensures partners receive credit for the call.

This document defines the interface for the both the ping and callback reporting method.

About the eLocal Call Ping 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 HTTP POST request

Development/Testing

While performing your development, eLocal will supply you with an API key. This key will be used to make requests against the eLocal service and validate that requests and responses are working as expected. The phone numbers returned will be test-only numbers; calls to the numbers will go to eLocal not to service providers. All requests 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 change the status of your account and you will start to receive correct phone numbers.

Ping Request

URL Path

/call/ping

JSON Format

{"ping": 
  {
    "key": "[value]",
    "zip_code": "[value]",
    "need_id": "[value]",
    "sender_id": "[value]",
    "sender_origin_key": "[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"
      }
    ]
  }
}

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 call so we can ensure we have a valid provider to accept the call. Often these are your own identifiers.varchar(255)9876
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
caller_idREQUIREDThe caller phone number for the lead. Should be 10 digits with no additional formatting.varchar(10)5556667777
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" }]

Ping Response

JSON Format

{"response": 
  {
    "status": "success|not_interested|error",
    "token": "[value]",
    "sender_id": "[value]",
    "message": "[value]",
    "phone_number": [value],
    "price": 5.55
  }
}

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
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
phone_numberREQUIREDThe phone number that the call should be sent to. The number format will include a leading + sign, followed by the country code (at this point always a 1 as eLocal clients are all US based businesses), followed by the number.varchar(12)+15555555555
priceREQUIREDThe price eLocal is willing to pay for the call.decimal5.55
billable_durationREQUIREDNumber of seconds that will make a call billable. This number may vary depending on the agreement with eLocal.integer3
display_nameOPTIONALThe name of the company that the call will be sent to. This field may be present depending on the agreement with eLocal.textWonka Industries

Example Request/Response

Using curl

Success

> curl -H 'Content-type: application/json' \\ -d '{"ping": {"zip_code":"19428", "need_id": "1000", "key":"YOUR_KEY_HERE",
	"questions": [
          {
            "question_text": "Existing customer?",
            "answer text": "No"
          },
          {
            "question_text": "commercial?",
            "answer_text": "No"
          }
        ] }}' \\ https://api.elocal.com/call/ping{"response":{"status":"success","token":"xesef-lesek-hutaf-cinex","phone_number":"+15555555555","price":"20.0"}}

Failure

> curl -H 'Content-type: application/json' \\ -d '{"ping": {"zip_code":"99556", "need_id": "1000", "key":"YOUR_KEY_HERE" }}' \\ https://api.elocal.com/call/ping{"response":{"status":"not_interested","message":"no coverage"}}

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, the winning bid's price and the winning bid's duration

URL Path

/call/final_pricing

JSON Format

{"final_pricing": 
  {
    "key": "[value]",
    "token": "[value]",
    "winning_bid": "[value]",
    "winning_duration": "[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
winning_durationOPTIONALTotal length, in seconds, for the billable duration required for the winning bid.integer60

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_duration": 35, "winning_bid": 65, "key":"YOUR_KEY_HERE" }}' \\ https://api.elocal.com/call/final_pricing{"response":{"status":"success", "token":"ximok-hesok-dovix"}}

Failure

> curl -H 'Content-type: application/json' \\ -d '{"final_pricing": {"token":"2S2S-A2SD-K48B", "winning_duration": 35, "winning_bid": 65, "key":"YOUR_KEY_HERE" }}' \\ https://api.elocal.com/call/final_pricing{"response":{"status":"error", "token":"ximok-hesok-dovix", "message": "Problem retrieving call information"}}