This API is organized around REST.

API endpoints accept JSON-encoded request bodies and return JSON-encoded responses.

The API uses standard HTTP response codes, authentication, and verbs.


All API requests must be made securely over HTTPS.

All API POST body requests must be encoded as JSON and sent with the "Content-Type: application/json" header.

API requests must be made over HTTPS and JSON-encoded.



A valid API key is required to access the API and a user token is required to identify and authenticate user sessions.

API Keys

The API key must be provided in an Authentication header using HTTP Basic authentication - use your API key as the username.

API keys must be kept secret and secure; do not share them publicly. Use them only in server-side requests.

DO NOT use API Keys in client-side code!


User Tokens

The user token must be provided in an Authentication header using HTTP Basic authentication - use the token as the password.

Unless otherwise noted*, requests must include a user token.

Use HTTP Basic authentication to pass your API Key and a user token.


Example of an API request using Basic authentication:

    curl -G \

* - a user token is not required for POST requests to 'api/v1/login', 'api/v1/account', and 'api/v1/profiles'; nor GET requests to 'api/v1/profiles', 'api/v1/countries', and 'api/v1/zones'.

Rate Limits

Each API key is allowed no more than 3,600 requests are per hour and 300,000 requests per month.

IP Whitelisting

You may opt-in to IP whitelisting for your API key.


All API responses are encoded as JSON and returned with the "Content-Type: application/json" header.

API responses are encoded and returned in JSON format.


All responses to invalid requests are formatted as follows:

    "status": [three digit HTTP Response Code, Integer],
    "error": [error message, String]

All responses to valid requests are formatted as follows:

    "status": [three digit HTTP Response Code, Integer],
    "token": [base64 encoded user token, String or Null],
    "data": [response data, Object],
    "requests": [rate limit info, Object]
    "error": [error message, String or Null]

All API responses to valid API requests include a user token, which is updated periodically for security purposes. Therefore, it is important to check the value of the `token` parameter returned in each API response for a potential update before sending the next request.

User Tokens are updated periodically.


All responses to valid API requests include the following rate limit information returned under the `requests` parameter for the API key supplied in the request:

    "used": [number of requests used this month, Integer],
    "remaining": [number of requests remaining this month, Integer],
    "resets": [date and time when counter resets in Atom format, String]


All responses to invalid API requests include an error message that contains an HTTP status code and a description.

Excessive invalid requests* will result in a temporary ban!


General Errors

  • 400 - Error: Client IP Address is required! (i.e. `REMOTE_ADDR` header missing or invalid)
  • 403 - Error: HTTPS is required!
  • 404 - Error: Resource not found! (i.e. API endpoint does not exist)
  • 405 - Error: Request method is not valid! (i.e. not GET or POST)
  • 500 - Sorry, something went wrong! (i.e. request was not processed successfully by the server)
  • 503 - Error: API is disabled!

POST Request Errors

  • 400 - Error: Malformed JSON
  • 400 - Error: Post body data is required!
  • 415 - Error: Content-Type 'application/json' is required!

API Key Validation Errors

  • 401 - Error: API key is required!
  • 403 - Error: API key has been disabled!
  • 403 - Error: IP is not whitelisted! (for API keys with IP whitelisting enabled)
  • 422 - Error: API key is not valid!
  • 429 - Error: Exceeded X requests in the last Y minutes!
  • 429 - Error: Exceeded Z requests in the last month!

API Endpoint Errors

  • 307 - Sorry, resource is temporarily not available!
  • 400 - Error: Parameter is missing or not valid!
  • 401 - Account not verified!
  • 401 - A Profile is required!
  • 401 - Profile has been disabled!
  • 401 - Error: Session is required! (for API endpoints that require a user token)
  • 403 - Login is required!
  • 404 - Error: Not found!

* - i.e. those returing a 400-level status code


Select an API endpoint below to learn more.


Contact us to inquire further about using the Tipalink API.