Skip to main content

Talroo Reporting API

note

Prior to using Talroo's Reporting API, please reach out to your Talroo POC to obtain your customer reference and customer secret, and to confirm your jobs include the necessary advertiser_id field.

How can I use the Reporting API?​

The Talroo Reporting API allows our customers to access their campaign statistics.

API Endpoint​

https://www.jobs2careers.com/reporting/

Required Fields​

The following fields MUST be included in the request URL:

  • customer_reference=
    • This string is unique to each customer and is provided by Talroo
  • advertiser_id=
    • This Id is provided to Talroo at the job-level within the job feed. This Id should be included in an <advertiser_id> tag.
  • timestamp=
    • System timestamp.
  • action=
    • Value must equal "get_clicks"
  • ticket=
    • HMAC-sha256 hash - Please use provided customer secret to generate this HMAC for each request.

Optional Fields​

The following fields may be added to the request URL:

  • start=
    • Start date of the report, YYYY-MM-DD format. If start is not included, default is yesterday’s date.
  • end=
    • End date of the report (inclusive), YYYY-MM-DD format. End value may NOT be set to a date before the start value.

Note: Data is available as far back as the previous two full calendar months.

Error Codes​

{"status":0,"message":"unauthorized request"}  
{"status":0,"message":"missing required params"}  
{"status":0,"message":"not found"}  
{"status":0,"message":"server is busy"}  
{"status":0,"message":"too many requests"}  
{"status":0,"message":"format error"}  
{"status":0,"message":"date format error"}  
{"status":0,"message":"invalid date range"}

Example Call​

Request URL:
https://www.jobs2careers.com/reporting/?customer_reference=637573746f6d6t5722e3430&advertiser_id=2112&action=get_clicks&timestamp=1565617926900&start=2019-05-01&end=2019-05-01&ticket=08860613caf5e0e6158gce9543d21635a0ed38b44t522d291d7e6a7e253e2

Sample JSON response​

{
  "status": 1,
  "start_day": "2019-05-01",
  "end_day": "2019-05-02",
  "total_clicks": 2,
  "clicks_report": {
    "2019-05-01": [
      {
        "click_id": "9e123d91-1e4f-4bbc-974f-a12d2202d087",
        "bid_type": "cpc",
        "price": "25",
        "time": "2019-05-01 00:11:46",
        "job_reference": "asdf123123123",
        "ip": "123.123.12.1",
        "url": "https://www.faketalroolandingpage.com",
        "tlr_sid": "9e123d91-1e4f-4bbc-974f-a12d2202d087",
        "platform": "iOS",
        "job_id": "123456987",
        "campaign_id": "12345",
        "campaign_name": "Fake Campaign 1"
      },
      {
        "click_id": "9e123d91-1e4f-4bbc-974f-a12d2202d088",
        "bid_type": "cpc",
        "price": "100",
        "time": "2019-05-01 00:14:30",
        "job_reference": "tyuityui12123321321",
        "ip": "123.123.12.1",
        "url": "https://www.faketalroolandingpage.com",
        "tlr_sid": "9e123d91-1e4f-4bbc-974f-a12d2202d088",
        "platform": "Device_m_Mobile",
        "job_id": "123456789",
        "campaign_id": "45612",
        "campaign_name": "Fake Campaign 2"
      }
    ]
  }
}

Sample JavaScript Code​

<!-- Import JQuery if not already added --> 
<!-- <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script> --> 
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/core-min.js"></script> 
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/hmac-sha256.js"></script> 

var SERVER = "https://www.jobs2careers.com/reporting/"; 

// input params 
var customer_ref = '637573746f6d65722e3430'; 
var pKEY = "Jobs2CareersDemo"; 
var advertiser_id = 0; 
var start = ''; 
var end = ''; 

// action = 'get_clicks'
// build request
function fetchRecords(action) {	
  var params = { 
    customer_reference: customer_ref, 
    advertiser_id: advertiser_id, 
    action: action, 
    timestamp: Date.now(), 
    start: start, 
    end: end 
    }; 
}

//query string 
var data = $.param(params); 

// generate ticket 
var hash = CryptoJS.HmacSHA256(data, pKEY); 
params["ticket"] = ""+hash; 
data = $.param(params); 

AJAX_CALL(data);