REST API

So you are building an integration with ReferralHero. GREAT! We're very excited that you want to add-on to our platform. Before you dive in and start coding, make sure you read this page to know how to structure your app.

Overview

The ReferralHero API is organized around REST. Our API has predictable, resource-oriented URLs. JSON is returned by all API responses, including errors.

ReferralHero API is in active development, hence expect things to change. We will add new endpoints and change minor details here and there, but if we introduce breaking changes we will notify you at least 2 weeks in advance.

API Endpoint

Calls for ReferralHero API are relative to the URL https://app.referralhero.com/api/v2

API Token

All API calls require the api_token parameter. You can find your API Token in your ReferralHero Account > API Page.

Your API token carries many privileges, so be sure to keep it secret! Do not share your secret API token in publicly accessible areas such GitHub, client-side code, and so forth.

Also, you should write back-end only code, since front-end code will expose your API token and can be used for malicious activities.

All API requests should be made over HTTPS. API requests without authentication will fail with the error code "no_token".

Responses

• Data is returned in JSON.

• Any non-200 HTTP response code can be considered an error.

Rate limiting

Currently, we apply a "soft" limit of 5,000 API calls per hour. Get in touch with us if you need to increase it. If your request rate exceeds our limits, you will receive an HTTP status of 429 with an error code "too_many_calls".

We hope you enjoy using our API and please report any bugs or unexpected behavior :)