Request / Response

The iScout API follows a simple JSON-RPC style request/response.



The Request

To make a request to the API, send a GET or POST request via HTTPS to the method's URL. The URL has this format:

https://api.iscout.com/v1/METHOD

REQUEST DATA

Any time you make a request, you must provide a plain, json-serialized request object. At the very least it will contain a token field (containing your token).

If you wish to make the response JSON more readable, then you may also include a pretty field set to true.

Each method may include additional fields in the request data (such as user):

{
  "token": "ABCD",
  "pretty": true,
  "user": 99
}

GET / POST

Each method may be executed via either a GET or POST request. GET requests should pass the request data's JSON as the query string:

GET https://api.iscout.com/v1/users.info?%7B%22token%22%3A%22ABCD%22%2C%22user%22%3A99%7D

POST requests should pass the request data's JSON as the body:

POST https://api.iscout.com/v1/users.info
{"token":"ABCD","user":99}


The Response

The response will always be a JSON object with an ok field set to either true or false.

FAILURE

If an error occurs, then ok will be false. There will be an error field which contains a error identifier. In some cases, there will also be a description field with an explanation.

{
  "ok": false,
  "error": "invalid_token",
  "description": "The token `TEST_TOKEN` was not found."
}
SUCCESS

If the request succeeds, then ok will be true. Depending on the method, other properties will be included in the response.

{
  "ok": true,
  "user": {
    "id": "ABCD",
    "name": "John Sample"
  }
}

NOTE: Keep in mind that if a request does not reach the API (or the response does not reach your application) then the error message provided by your ISP, etc will likely not be JSON object with the given format.



Response Code

All responses will always have a status code of 200 (OK). This includes error responses.



Response Headers

All requests to the API will also include the following response headers:

Response Header Example Description
HZS-Request-ID DA234C08AF6F An alpha-numeric ID assigned to this specific request. Can be used for debugging request with tech support.
HZS-Response-Time 28 How long the server took to process the request (in ms).