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

Request Details

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

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/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

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