Welcome to IOSCO's International Securities & Commodities Alerts Network (I-SCAN) API v1 documentation.

This document explains how to configure your servers to communicate directly with the IOSCO API.

This API lets you query the warnings database using RESTful requests.

For more information on REST APIs, we recommend reading the Postman Blog. We also recommend downloading the Postman app to facilitate with your testing. The Postman app is available for free here.

Making A Request

The URI for API v1 requests is always https://api.iosco.org/v1/i-scan/warnings

All requests must be made over HTTPS. For security reasons, the API does not support HTTP.

Authorization Header

IOSCO's API uses API keys to identify the servers connecting to the API. To request an API key, please contact api@iosco.org.

The API expects an API key to be passed as a Bearer Token in an Authorization header.

Set a plain text header named "Authorization" with the contents of the header being "Bearer XXX" where XXX is your API Key.

Example Header

    GET https://api.iosco.org/v1/i-scan/warnings HTTP/1.1
    Authorization: Bearer XXX

cURL Example

    curl -X "GET" "https://api.iosco.org/v1/i-scan/warnings" -H "Authorization: Bearer XXX" -H "Content-Type: application/json"

Suggestions On How to Secure Your API Key

We recommend that you not store the API key within your source code. Storing the API key as an environment variable keeps it from being revealed if your source code gets uploaded to a public repository. You can also store the API key in secure files located outside your application's source directory or use a password management service.

If you would like to rotate your API key or would like a new one, please contact api@iosco.org.

Formatting Your Request

Content-Type Header

All responses are returned in JSON format. We specify this by sending the Content-Type header.

    GET https://api.iosco.org/v1/i-scan/warnings HTTP/1.1

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "foo": "bar"
    }

Successful Requests

The API will return an array of warning objects when a request is successful.

Errors

Sometimes your API call will generate an error. Below is a summary of what to expect if you don't format your request properly, or we fail to properly process your request.

Failed Requests

If status code 400 is returned, it will be accompanied with an object containing an array of 1 or more error messages.

    GET https://api.iosco.org/v1/i-scan/warnings HTTP/1.1

    HTTP/1.1 400 BAD REQUEST
    Content-Type: application/json

    {
        "errors": [
            {"key": "field1", "message": "error message explained"},
            {"key": "field2", "message": "error message explained"},
            {"key": "field3", "message": "error message explained"},
        ]
    }

Too Many Requests/Rate Limit Exceeded

There is currently a rate limit of 10 HTTP requests per second. If this limit is exceeded, your IP address will be blocked for 1 hour.

Status Codes

Below is a table containing descriptions of the various status codes we currently support.