Returnam API

Create, manage and real-time track your links with our powerful and scalable APIs.

The API endpoint domain has changed!

Please update your endpoints from to

April 26, 2020: Analytics endpoint URLs have changed!

An unexpected update in the structure of our backend has forced us to change the endpoint URLs for Analytics without previous notice. Please update them accordingly.


Welcome to the Returnam API! If you're looking to create and manage links, or retrieve link analytics programmatically, you've come to the right place.

The documentation is divided into 3 sections. Links, Analytics and Hits:

  • Links provide all the necessary methods to create and manage links.

  • Analytics provide statistics about your links, including number of clicks, device types and geographical locations.

  • Hits provide more detailed information about individual clicks (hits) on your links. These methods provides more detailed information about each click (hit), such as operating system, browser, city, region and country.

Getting Started

Let's start with the basics. Please read this information before you move on to the rest of the documentation.

Create an account

To access our API, you'll need an account. It's free and you can get it here. Once you have verified your account, you'll receive an email with your API key and secret. Please save your credentials, you won't be able to get them or generate new ones.

Make sure you use an email which you have access to. We will send the API key and secret to that email.

Authentication headers

You'll need to add the API key and secret in the headers of every request to our API:

curl -X POST \ \
-H 'Content-Type: application/json' \
-H 'x-rtrn-key: <YOUR API KEY HERE>' \
-H 'x-rtrn-secret: <YOUR API SECRET HERE>'

Rate limits

Rate limits apply even when making authenticated calls. This is to prevent abuse and spam in the service. Rate limits for authenticated accounts are higher, but if reached, a 5 minute ban will be applied to the IP. An error 429 "Too many requests" will be returned.

"name": "TooManyRequestsError",
"message": "API requests limit reached. Try again in a few minutes.",
"code": 429

Error responses

Error responses are always composed of these 3 fields:

  • name: name of the error

  • message: details/reason about the error

  • error: http status code of the error

Here are some examples of error responses:

"name": "InvalidContentError",
"message": "Not a valid URL",
"code": 400
"name": "ResourceNotFoundError",
"message": "Link <5U6k_GDbV> not found",
"code": 404