NAV
shell

Introduction

Welcome to the Referral Factory API documentation.

Our API is organized around REST, and is designed to be a predictable and intuitive interface for interacting with your referral campaigns and the users participating in them. To use our API you will need to be on at least the Basic plan of Referral Factory.

Using our API you will be able to:

These functions will allow you to successfully scale your referral program, without having to increase the manual workload needed to manage it.

Referral Factory currently does not have a test mode, so please use the API functions carefully as you will be working with real user records.

If you have any additional questions please contact support.

Getting started

The Referral Factory API allows users to log in to their account without exposing their credentials. The process involves several steps:

Acquire an access token from your /settings tab - you can also get a new token from the same place at any time. Then use this access token to make authenticated requests.

Please note: if you were issued a refresh token, please generate a new access token

You can view code examples in the dark area to the right.

Authentication

Referral Factory uses API keys to allow access to the API.

Obtain API keys

Log in to your Referral Factory account, you will need to be on at least the Basic plan of Referral Factory. From the left sidebar menu, click the Settings tab, scroll down to the “API” section, and generate your API Access Token (or API key).

Security

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: Bearer your_access_key"

Make sure to replace your_access_key with your API access key.

All requests must be authenticated with the access token supplied in the Authorization header, using the Bearer scheme.

The Bearer authentication scheme was originally created as part of OAuth 2.0 in RFC 6750, but is sometimes also used on its own. Similarly to Basic authentication, Bearer authentication should only be used over HTTPS (SSL).

You may only have one active API Access Token at a time, per Referral Factory account. Acquiring a new access token will invalidate any other token you own for that account.

We expect the API key to be included in all your API requests to the server, in a header that looks like the following:

Authorization: Bearer your_access_key

Filters

To filter your requested data, you can add operators to your requests.

This section explains how to filter your requested data, manage ordering, and get relations with items in the supplied response (for example: get data from a specific user and include the referrer in the supplied response).

All list operations will be paginated.

Filtering

How to get all campaigns that have been launched:

  curl -G "https://referral-factory.com/api/v1/campaigns" \
  -H "Authorization: Bearer your_access_key" \
  -d "filters[0][field]=status" \
  -d "filters[0][value]=launched"

How to get all campaigns which have a reach of more than 10:

  curl -G "https://referral-factory.com/api/v1/campaigns" \
  -H "Authorization: Bearer your_access_key" \
  -d "filters[0][field]=reach" \
  -d "filters[0][operator]=gt" \
  -d "filters[0][value]=10"

How to get all campaigns that include "amp" in the campaign name:

  curl -G "https://referral-factory.com/api/v1/campaigns" \
  -H "Authorization: Bearer your_access_key" \
  -d "filters[0][field]=name" \
  -d "filters[0][operator]=like" \
  -d "filters[0][value]=amp"

This endpoint retrieves the filtered items.

A request could have more than one filter in a single request. eg: .../items?filters[index][field]=filterColumn&&filters[index][operator]=lte&&filters[index][value]=filterValue

Here are the supporting operators:

Operator Description
"equal" Use as "=" operator, this is default value
"gt" Use as ">" operator
"lt" Use as "<" operator
"gte" Use as ">=" operator
"lte" Use as "<=" operator
"like" Checking if value in requested column contains requested filterValue

Ordering

How to order campaigns by reach value:

  curl -G "https://referral-factory.com/api/v1/campaigns" \
  -H "Authorization: Bearer your_access_key" \
  -d "order[field]=reach" \
  -d "order[direction]=desc"

This endpoint retrieves ordered items.

You can have only one ordering filter and it should have the following parameters.

Parameter Description
field The field name from JSON response of the donor
direction Supported values: "asc", "desc". NOT required, default value is "asc"

Relations

The request example how to get single related data of users:

  curl "https://referral-factory.com/api/v1/users"\
  -H "Authorization: Bearer your_access_key" \
  -d "with=campaign"

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "first_name": "John",
      "email": "john@example.com",
      ...
      campaign : {...}
    },
    ...
  ]
}

The request example how to get all related data of users:

  curl "https://referral-factory.com/api/v1/users"\
  -H "Authorization: Bearer your_access_key" \
  -d "with=all"

The request example how to get multiple related data of items:

  curl "https://referral-factory.com/api/v1/users"\
  -H "Authorization: Bearer your_access_key" \
  -d "with[]=campaign" \
  -d "with[]=referrer"

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "first_name": "John",
      "email": "john@example.com",
      ...
      campaign : {...},
      referrer : {...}
    },
    ...
  ]
}

This endpoint return donor with transactions.

You can have more then one parameters for relations.

We also supporting all value for with to return all possible relations for current resource.

eg: .../users?with=all

Parameter Description
Supported value types string, array
Supported value for returning all relations "all"

Select Fields

Request example #1. How to get only the id and name fields of campaigns:

  curl -G "https://referral-factory.com/api/v1/campaigns" \
  -H "Authorization: Bearer your_access_key" \
  -d "fields=id,name"

Request example #2. How to get only the id and name fields of a nested object:

  curl -G "https://referral-factory.com/api/v1/campaigns" \
  -H "Authorization: Bearer your_access_key" \
  -d "with=campaign" \
  -d "fields.campaign=id,name"

This endpoint retrieves selected columns to add detail to the response. It is also possible to customize the response fields for nested objects (relations).

You can use the fields property in a request with comma-separated fields eg: id,name,reach

Campaigns

This section covers the details of your campaigns. You will have to build, customise and launch your campaign (otherwise known as a referral program) from inside the Referral Factory platform - you cannot create campaigns via the API. To create a campaign you’ll need to log into your account and navigate to the ‘Campaigns’ tab, you can launch the drag-and-drop campaign builder from here.

Once your campaign is up and running, you can use the API to read and manage your campaign details. You can also use the API to access and update the details of all users who join your campaign - either as the person referring, or the person invited.

Campaign Fields

Below is a list of all the fields related to a running campaign with Referral Factory. You can use these statistics to create dashboards and reports.

Field Type Description
id numeric The ID of the campaign to retrieve
name string The name of the current campaign
url string The unique join link for the current campaign
code string The unique code of the current campaign
reach numeric The reach of the current campaign (how many people it’s reached)
live boolean Shows if campaign is available now
status string Shows the campaign status. Possible values could be: 'launched', 'draft', 'paused’.
starts_at datetime Shows if the campaign will be started at a date in the future. If this value is null it means that campaign is already live.
ends_at datetime Shows if the campaign will expire at a date in the future. If this value is null it means the campaign will be live forever, unless it is manually paused or deleted from the dashboard.

Get All Campaigns

  curl -G "https://referral-factory.com/api/v1/campaigns" \
  -H "Authorization: Bearer your_access_key"

The above command returns JSON structured like this:

{
  "data": [
    {
          ...
          "name": "Example Campaign",
          ...
    },
    ...
  ],
  "links": {
    "first": "https://referral-factory.com/api/v1/campaigns?page=1",
    "last": "https://referral-factory.com/api/v1/campaigns?page=4",
    "prev": null,
    "next": "https://referral-factory.com/api/v1/campaigns?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 4,
    "path": "https://referral-factory.com/api/v1/campaigns",
    "per_page": 25,
    "to": 25,
    "total": 76
  },
  "code": 200,
  "message": null
}

This endpoint retrieves all campaigns.

HTTP Request

GET https://referral-factory.com/api/v1/campaigns

Get a Specific Campaign

  curl -G "https://referral-factory.com/api/v1/campaigns/1" \
  -H "Authorization: Bearer your_access_key"

The above command returns JSON structured like this:

{
  "data": {
          ...
          "name": "Example Campaign",
          ...
  },
  "code": 200,
  "message": null
}

This endpoint retrieves a specific campaign.

HTTP Request

GET https://referral-factory.com/api/v1/campaigns/<ID>

URL Parameters

Parameter Description
ID The ID of the campaign to retrieve

Users

Our API allows you to see, update and delete any users in a campaign. This is the most common use case of our API, as it allows you to manage the users in your referral campaign without having to log into our platform.

Once your campaign is live, you can use this part of the API to do things like: send new referred users to a CRM by consuming an endpoint, qualify referred users who meet certain conditions, see which users need rewards, and more.

User Fields

For any campaign, you can see the details of the users in that campaign. Below is a table of all the available user fields:

Field Type Description
id numeric The ID of the user to retrieve
campaign_id numeric The ID of the campaign for a user
qualified boolean Shows if the referred user is qualified or not
first_name string The first name of a user
email string The email address of a user
code string The unique code of user
source string Shows where a user came from. Possible values are: Direct, Referred, Added, API.
date datetime The date the user joined the campaign
url string The unique referral url for a user (their referral link)
meta array Shows the additional information about user, this info comes from input fields you add in the campaign

Get All Users

  curl -G "https://referral-factory.com/api/v1/users" \
  -H "Authorization: Bearer your_access_key"

The above command returns JSON structured like this:

{
  "data": [
    {
          ...
          "first_name": "John",
          "email": "john@example.com",
          ...
    },
    ...
  ],
  "links": {
    "first": "https://referral-factory.com/api/v1/users?page=1",
    "last": "https://referral-factory.com/api/v1/users?page=4",
    "prev": null,
    "next": "https://referral-factory.com/api/v1/users?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 4,
    "path": "https://referral-factory.com/api/v1/users",
    "per_page": 25,
    "to": 25,
    "total": 76
  },
  "code": 200,
  "message": null
}

This endpoint retrieves all users.

Supported relations: users

HTTP Request

GET https://referral-factory.com/api/v1/users

Get a Specific User

  curl -G "https://referral-factory.com/api/v1/users/1" \
  -H "Authorization: Bearer your_access_key"

The above command returns JSON structured like this:

{
  "data": {
          ...
          "first_name": "John",
          "email": "john@example.com",
          ...
  },
  "code": 200,
  "message": null
}

This endpoint retrieves a specific user.

Supported relations: users

HTTP Request

GET https://referral-factory.com/api/v1/users/<ID>

URL Parameters

Parameter Description
ID The ID of the user to retrieve

Create a New User

    curl "https://referral-factory.com/api/v1/users" \
    -H "Authorization: Bearer your_access_key" \
    -X POST \
    -d "campaign_id=1&&first_name=John&email=john@example.com"

The above command returns JSON structured like this:

{
    "data": {
          ...
          "campaign_id": 1,
          "qualified": false,
          "first_name": "John",
          "email": "john@example.com",
          ...
    },
    "code": 201,
    "message": "User successfully added."
}

This endpoint creates a new user. You can use this functionality to create a new user in your referral campaign, at the same time as that user registers on your website (for example). This means the user does not have to register on your website, and then register again to get a referral code. Required fields to create a user are *first_name, email, campaign_id

HTTP Request

POST https://referral-factory.com/api/v1/users

Request Parameters

Parameter Required Type Validation
first_name YES string First Name of the user
email YES email Email address of the user
campaign_id YES numeric ID of campaign where should be added user

Update a Specific User

    curl "https://referral-factory.com/api/v1/users/1" \
    -H "Authorization: Bearer your_access_key" \
    -X PUT \
    -d "qualified=1"

The above command returns JSON structured like this:

{
    "data": {
          ...
          "campaign_id": 1,
          "qualified": true,
          "first_name": "John",
          "email": "john@example.com",
          ...
    },
    "code": 200,
    "message": "User successfully updated."
}

This endpoint updates a specific user. This can be used when a status change happens, or a referral is qualified, or there is a change in information about the user.

HTTP Request

PUT https://referral-factory.com/api/v1/users/<ID>

URL Parameters

Parameter Description
ID The ID of the device to update

Request Parameters

Parameter Required Type Validation
qualified Yes boolean use 1 or 0 to qualify or unqualify users manually

Delete a Specific User

    curl "https://referral-factory.com/api/v1/users/1" \
    -H "Authorization: Bearer your_access_key" \
    -X DELETE

The above command returns JSON structured like this:

{
    "data": {
          ...
          "campaign_id": 1,
          "qualified": true,
          "first_name": "John",
          "email": "john@example.com",
          ...
    },
    "code": 200,
    "message": "User successfully deleted."
}

This endpoint deletes a specific item.

HTTP Request

DELETE https://referral-factory.com/api/v1/users/<ID>

URL Parameters

Parameter Description
ID The ID of the item to delete

Errors

Errors should be returned as JSON structured like this:

    {
        "code": 400,
        "message": "Validation errors in your request",
        "errors": {
            "email": [
                {
                    "field": "email",
                    "message": "The email field is required."
                }
            ]
        }
    }

The Referral Factory API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is incorrect.
403 Forbidden -- The resource requested is marked for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't in JSON format.
410 Gone -- The resource requested has been removed from the data server.
429 Too Many Requests -- You're requesting too many resources at one time.
500 Internal Server Error -- We had a problem with our server. Please try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.