Conversion Reporting¶
The Conversion Reporting API (formerly referred to as the “Call Center” or “Sales Reporting” API) is used to report completed order information (or other conversion events) from a server back into the platform. Reporting order information through the API allows advertisers to compensate publishers for sales that convert over the phone (or on the web). Additionally, Advertiser Direct campaigns using the Conversion Reporting API with search campaigns can report back revenue generated for each phone call so that search bids can be optimized.
Before using the Conversion Reporting API, request credentials from questions@invoca.com
Client API Wrappers¶
The following working examples with wrapper code to integrate in Ruby, Java, PHP or .NET are available:
POST (or PUT) to a URL¶
Send call results to Invoca servers in the form of an HTTP POST. cURL is recommended because it is simple and preinstalled on most machines. The extended example later in this document breaks down each part of a cURL POST.
Here is an example of a URL POST:
https://api0.invoca.net/api/2014-04-15/calls/23.xml
where “” is the API version and “23” is the Conversion Reporting ID (previously known as Call Center ID) for your account on the platform.
For “Publisher Promotion” or Fixed Price “Bundled” campaigns, the Conversion Reporting ID is found on the Campaign Summary tab, Integration section.
Remember to check the HTTP status code returned for error checking. This helps greatly when debugging.
Parameters¶
Passed in standard HTML “application/form-url-encoded” format. Put quotes around all parameter values being passed in the API call.
Report a sale/conversion on a call¶
Required
start_time_t: 10 digit start time of the call in UTC seconds since 1/1/70, also known as Unix time_t. The start time does not have to be exact since clocks will not be perfectly synchronized.
Additionally, one of the following two parameters is highly recommended:
calling_phone_number: ANI in E.164 format +country national_number; example: ‘+18885551212’.
duration_in_seconds: Length of the call. Used for finding the call that drove the sale, not used to check against payout conditions. Like start time, duration_in_seconds does not have to be exact, we use it find the closest match.
Optional
reference_id: (call_center_call_id): This ID must be unique for each call across a call center’s calls. The ID is set the first time the call result is POSTed for a call. To update the call result, use the same ID.
called_phone_number: DNIS in E.164 format +country national_number; example: ‘+18885551212’. UK and Spanish numbers are also supported. Their country codes are +44 and +34 respectively.
use_http_status: 1 or blank will use HTTP status corresponding to success/failure. If set to 0, the HTTP status will always be 200 OK and the actual status and error message will be in the response body. See the Status section below.
Report a new web conversion¶
Required
web_conversion: Set to “1” to indicate a conversion that is not tied to a call (default is 0).
reference_id: This ID must be unique for each conversion.
advertiser_campaign_id: The ID of the advertiser campaign in the platform.
affiliate_id_from_network: The affiliate or publisher ID (of the main network) that is credited for the web conversion; the publisher must be approved to the advertiser campaign specified above.
Optional
use_http_status: 1 or blank will use HTTP status corresponding to success/failure. If set to 0, the HTTP status will always be 200 OK and the actual status and error message will be in the response body. See the Status section below.
Add to an existing web conversion¶
Required
web_conversion: Set to “1” to indicate a conversion that is not tied to a call (default is 0).
parent_reference_id: This is the reference_id that was passed in when creating the initial web conversion.
Optional
use_http_status: 1 or blank will use HTTP status corresponding to success/failure. If set to 0, the HTTP status will always be 200 OK and the actual status and error message will be in the response body. See the Status section below.
Status¶
The HTTP status returned is 201 Created for a successful POST (or a 200 OK for a successful PUT), a 4xx code if one of the parameters is incorrect, or a 5xx code if a server error occurred. In the latter two error cases, a detailed error class and message are returned in XML in the body, for example:
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Class>NotFound</Class>
<Message>Couldn't find call around time 1262895406 from caller +1 8053825533
</Message>
</Error>
If &use_http_status=0 is given, the status is always returned as 200 Ok or 201 Created. This can be helpful in order to see the detailed error message in the body when working with HTTP libraries that just return the status code when there are errors without exposing the body.
Security¶
All posts must use HTTPS BASIC authentication and use pre-assigned usernames and passwords. Contact questions@invoca to request Conversion Reporting API credentials.
High availability¶
The initial POST should choose randomly (or alternately) between api0.invoca.net and api1.invoca.net. If a POST fails for any reason, retry the POST on the other one.
Idempotency¶
Sales are considered unique using a combination of start_time_t + SKU_list + reason code. POSTs with duplicate keys (same call, sku list, reason code) behave as follows:
If the values passed are unchanged, the reported conversion remains unchanged and is not duplicated.
If different values are passed, the original conversion is updated with the new values.
POSTs with unique keys always create new conversion transactions.
Frequency¶
Updates can be sent at any frequency from once a minute to once a day. Customers prefer to get their data as fast as possible, so the best practice is to get as close to once a minute as practical.
Example¶
The example below uses cURL to demonstrate a POST that updates a call.
curl -u '[email protected]:secretPW'` \
'https://api0.invoca.net/api/2014-04-15/calls/23.xml' -k -v \` \
-d reference_id='2935812450' \
-d start_time_t='1273589993' \
-d duration_in_seconds=300 \
-d called_phone_number='+18773593504' \
-d calling_phone_number='+12143283408' \
-d reason_code='S' \
-d sku_list[]='DVD' \
-d quantity_list[]=2 \
-d sku_list[]='cleaner' \
-d quantity_list[]=1 \
-d sale_currency='USD' \
-d sale_amount='60.50' \
-d email_address='[email protected]' \
-d opt_in_SMS='1' \
-d name='Jane Doe' \
-d address1='123 Mockingbird Lane' \
-d address2='Unit 2' \
-d order_city='Chicago' \
-d state_or_province='IL' \
-d country='US' \
-d cell_phone_number='+13125170488' \
-d use_http_status='1'</code></pre>
Output:
HTTP/1.1 201 Created
Date: Fri, 25 Jun 2010 18:22:45 GMT
Server: Mongrel 1.1.5
Status: 201
X-Runtime: 189
Cache-Control: no-cache
Content-Type: application/xml; charset=utf-8
Content-Length: 1
Set-Cookie: SERVERID=; Expires=Thu, 01-Jan-1970 00:00:01 GMT; path=/
Via: 1.1 www.invoca.net
Vary: Accept-Encoding
Example Breakdown¶
This is a description of some of the parameters in the previous cURL example.
curl -u ‘example@callcenter.api:secretPW’ If using cURL, this is how credentials are passed. The username is ‘example@callcenter.api’ and the password is ‘secretPW’. The two strings need to be separated with a colon character.
‘https://api0.invoca.net/api/2014-04-15/calls/23.xml’ -k -v The URL where the call result is sent. The API version is “2014-04-15” and the unique Conversion Reporting ID is “23”.
-d reference_id=’2935812450’ This ID (if provided) needs to be unique for each call within a call center, and is the handle for future updates on this call or conversion.
-d start_time_t=’1273589993’ The call start time in UTC.
-d called_phone_number=’+18773593504’ The phone number the caller dialed.
-d calling_phone_number=’+12143283408’ The phone number the caller is calling from.
-d sku_list[]=’DVD’
-d quantity_list[]=2
-d sku_list[]=’cleaner’
-d quantity_list[]=1 sku_list and quantity_list are closely related. The quantity_list must appear in the same order as the sku_list. For this example, the sku DVD has a quantity value of 2 while cleaner is 1.
Search Algorithm to Find Matching Call¶
We look for an exact match for calls associated with the call center, using these parameters, if given:
reference_id calling_phone_number
If more than one call is found with those exact parameters (or the parameters are not provided), we then look for calls that are closest to the start_time_t and duration_in_seconds, if provided. Due to the distribution of call attribute data, the start_time_t parameter is given a different weight than duration_in_seconds so that a call with a start time difference of 20 seconds is equivalent to a call with a duration difference of 1 second.
Please note that the Conversion Reporting API is idempotent (if you repost sales data already captured, it is not accidentally counted twice), so repost any sales that receive a failure.
Endpoint:¶
https://invoca.net/api/2014-04-15/calls/<converstion_reporting_id>.xml