Report

The Report endpoint is provided to allow API users to send "report events" relating to interactions with each business listing back to Sensis. It takes userIp, userAgent, userSessionId and id parameters to provide information associated with each reporting event.

See also: Reporting Usage Events for more information.

Endpoint URL

http://api.sensis.com.au/v1/<env>/report/<eventName>

where env is the report to send the request to. Can be either test or prod. Use HTTP POST method to submit report requests, HTTP GET method is deprecated for report endpoints.

Note: A list of valid eventName values are listed in the Name column on the Event Types table at Reporting Usage Events.

Parameters

The Report endpoint takes the following parameters:

Name Type Description Remarks
key string API key (required) See Authenticating for details.
userIp string IP address of user accessing your application (required) See Reporting Usage Events for details.
id string reportingId of listing associated with event (required) The reportingId field provided in each listing returned in a search response. Multiple id parameters can be added where the same event applies to each listing, except where the content parameter is specified. See Reporting Usage Events for details.
userAgent string User agent of user accessing your application For example, from the user-agent HTTP header. See Reporting Usage Events for details.
userSessionId string Session id of user accessing your application See Note below.
content string Specific content to which the event applies (required) Only required for certain events. See Reporting Usage Events for details.

Note: We request that you provide the userSessionId so that we can track a user's interaction with your application. It does not have to be the actual session id per se. For example, you may provide a derived value such as a hash of session id. This would be acceptable so long as a user's interaction with your application can be identified.

Response Message

HTTP content type: application/json

The response message is a JSON object containing the following members.

Name Type Description Remarks
validationErrors array Validation error messages (if any). Returns an array of strings, one message per array item.
validationWarnings array Validation warning messages (if any). Returns an array of strings, one message per array item.
date string Date and time according to the server. For example: 2011-02-28T12:01:02.345+1000.
time number Time taken to process the request. Reported in milliseconds.
code number Response code. Indicates success, failure or partial success (see below).
message string Response message. Contains an error message (if any).

Result

HTTP Status

The Report endpoint will always return HTTP 200 on success. See HTTP Status Codes for possible error codes.

Status Codes

The following status codes can be returned in the code field:

Code Description Remarks
200 Success The report event was successful.
206 The report event contained validation errors May occur where some of the id parameters sent are invalid. Successful report events will only be captured for the valid id(s).
400 Validation error Invalid or missing input parameters given. See Validation Errors.

Example

See also: Reporting Usage Events for a list of all events which can be reported and sample java code to submit report events.

See also: Examples for how to call endpoints from code.