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. Please make sure you understand how our campaign builder works before interacting with our API, you can watch to learn here.

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. Most developers use the example campaigns that are pre-populated in your dashboard for testing.

If you have any additional questions please contact our technical support team on developers@referral-factory.com. Our developers are ready and on hand to help you get your referral program up and running 🧑‍💻🚀

API Limits

Our engineering team closely monitors usage of the Referral Factory public APIs, to ensure a quality experience for all our customers. Below, you'll find the limits by which a single application (as identified by an access token) can consume the Referral Factory public APIs.

Burst limit: 600 API calls per one minute.

Please throttle your API calls accordingly, to avoid reaching your limits. Please also note that if you abuse your limits more than three times, your application IP will automatically be blocked from accessing our API for the next 7 days.

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 : {...}
    },
    ...
  ]
}

You can have more then one parameters for relations.

We also support 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

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

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "first_name": "John",
    "email": "john@example.com",
    "referrer_id": 10,
    "campaign_id": 25,
    "qualified": false,
    "qualified_at": null,
    "unsubscribed": false,
    "unsubscribed_at": null,
    "code": "{random-code}",
    "url": "https://{subdomain}.referral-factory.com/{random-code}",
    "meta": {},
    "sharing": [
      {
        "social": "facebook",
        "url": "https://referral-factory.com/{random-code}/socials/facebook"
      },
      {
        "social": "whatsapp",
        "url": "https://referral-factory.com/{random-code}/socials/whatsapp"
      }
    ],
    "sharing_message": {
      "subject": "message subject",
      "text": "message text"
    },
    "campaign": {
      ...,
      "id": 25,
      "name": "Example Campaign",
      ...
    },
    "referrer": {
      ...,
      "id": 10,
      "first_name": "Kris",
      "email": "krismarrier@gmail.com",
      ...
    },
    ...
  }
}

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
referrer_id numeric The ID of the user who referred you
qualified boolean Shows if the referred user is qualified or not
qualified_at datetime Shows when the referred user is qualified or returns null if not qualified
unsubscribed boolean Shows if the user is unsubscribed from notifications
unsubscribed_at datetime Shows when the user is unsubscribed from notifications
first_name string The first name of a user
email string The email address of a user
code string The unique code of user
reach numeric Shows total reaches count for current user unique URL
referrals_count numeric Shows total referrals count for current user
converted_referrals_count numeric Shows converted referrals total count for current 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 The additional information about user, this info comes from the form fields you add inside the campaign builder.
sharing array The additional information about social media, this info comes from the form campaign builder to show your social media link and type.

User 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: {
          ...
          "name": "Example 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" \
  -d "with[]=rewards_due" \
  -d "with[]=rewards_issued"

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "first_name": "John",
      "email": "john@example.com",
      ...
      campaign: {
          ...
          "name": "Example Campaign",
          ...
      },
      referrer: {
          ...
          "first_name": "James",
          "email": "james@example.com",
          ...
      },
      rewards_due: {
        ...
        "reward_id": "1",
        "reward_name": "Example Reward 1",
        ...
      },
      rewards_issued: {
        ...
        "reward_id": "2",
        "reward_name": "Example Reward 2",
        ...
      }
    },
    ...
  ]
}

Supported relations: campaign and referrer and rewards_due and rewards_issued

We also support 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"

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 by chunks. by default in each chunk you will retrieve 25 users, if you want to get more users in each chunk you can add per_page parameter in your request (eg: https://referral-factory.com/api/v1/users?per_page=100).

Maximal value of per_page is 250. You can always get your next chunk using links -> next property in your response.

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",
    "sharing": [
      {
        "social": "facebook",
        "url": "https://referral-factory.com/{random-code}/socials/facebook"
      },
      ...,
      {
        "social": "sms",
        "url": "https://referral-factory.com/{random-code}/socials/sms"
      }
    ],
    "sharing_message": {
      "subject": "message subject",
      "text": "message text"
    },
    "rewards_due": [
      {
        "reward_id": 1,
        "reward_name": "Example Reward",
        "reward_value": 50,
        "rewards_total": 2,
        "rewards_value": 100,
        "referrer_name": "John",
        "referrer_email": "john@example.com",
        "issued_at": null,
        "in_cart": false
      },
      ...
    ],
    "rewards_issued": [
      {
        "reward_id": 2,
        "reward_name": "Example Reward 2",
        "reward_value": 70,
        "rewards_total": 1,
        "rewards_value": 70,
        "referrer_name": "Mary",
        "referrer_email": "mary@example.com",
        "issued_at": null,
        "in_cart": false
      },
      ...
    ],
    ...
  },
  "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": {
          "id": 1,
          "first_name": "John",
          "email": "john@example.com",
          "referrer_id": 10,
          "campaign_id": 25,
          "qualified": false,
          "qualified_at": null,
          "unsubscribed": false,
          "unsubscribed_at": null,
          "code": "{random-code}",
          "url": "https://{subdomain}.referral-factory.com/{random-code}",
          "meta": {},
          "sharing": [
              ...,
              {
                "social": "facebook", 
                "url": "https://referral-factory.com/{random-code}/socials/facebook",
              },
              {
                "social": "whatsapp",
                "url": "https://referral-factory.com/{random-code}/socials/whatsapp",
              },
              ...
          ],
          "sharing_message": {
            "subject": "message subject",
            "text": "message text"
          },
          "campaign": {
              ...,
              "id": 25,
              "name": "Example Campaign",
              ...
          },
          "referrer": {
              ...,
              "id": 10,
              "first_name": "Kris",
              "email": "krismarrier@gmail.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
referrer_id NO numeric ID of referrer if exists
referrer_code NO string Code of referrer if exists
notify NO boolean Send this property only if you want to send notification to created 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": {
        "id": 1,
        "first_name": "John",
        "email": "john@example.com",
        "referrer_id": 10,
        "campaign_id": 25,
        "qualified": true,
        "qualified_at": "2023-12-04T12:35:17.000000Z",
        "unsubscribed": false,
        "unsubscribed_at": null,
        "code": "{random-code}",
        "url": "https://{subdomain}.referral-factory.com/{random-code}",
        "meta": {},
        "sharing": [
          ...,
          {
            "social": "facebook",
            "url": "https://referral-factory.com/{random-code}/socials/facebook",
          },
          {
            "social": "whatsapp",
            "url": "https://referral-factory.com/{random-code}/socials/whatsapp",
          },
          ...
        ],
        "sharing_message": {
          "subject": "message subject",
          "text": "message text"
        },
        "campaign": {
          ...,
          "id": 25,
          "name": "Example Campaign",
          ...
        },
        "referrer": {
          ...,
          "id": 10,
          "first_name": "Kris",
          "email": "krismarrier@gmail.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
first_name No string The first name of a user
email No string The email of a user
qualified No 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

Rewards

Our API allows you to see, what reward you should give, or have you already given to the user. This is the most common use case of our API.

Reward Fields

Here you can see the details of the reward for you. Below is a table of reward fields:

Field Type Description
id numeric The id of the reward
campaign_id numeric The id of the campaign for a reward
name string The name of the reward
reward_for string The type of user
type string The type of reward
value numeric The value of reward that are due to be issued to a user
when_referral string When the reward was assigned

Reward Relations

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

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "campaign_id": 5,
      "name": "Example reward name",
      "reward_for": "Person Invited (Referred User)",
      "type": "Amazon Voucher",
      "value": 50,
      "when_referral": "invited"
    },
    {
      "id": 2,
      "campaign_id": 10,
      "name": "Example 2 reward name",
      "reward_for": "Person Referring (Direct User)",
      "type": "Cash Digital Card",
      "value": 35,
      "when_referral": "converted"
    },
    ...
  ],
  "links": {
    "first": "https://referral-factory.com/api/v1/rewards?page=1",
    "last": "https://referral-factory.com/api/v1/rewards?page=3",
    "prev": null,
    "next": "https://referral-factory.com/api/v1/rewards?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://referral-factory.com/api/v1/rewards",
    "per_page": 25,
    "to": 25,
    "total": 70
  },
  "code": 200,
  "message": "Paginated rewards response"
}

This endpoint receives the rewards that are due to be issued.

The request example how to get related data of rewards:

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

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "campaign_id": 5,
      "name": "Example reward name",
      ...
      campaign: {
          ...
          "name": "Example Campaign",
          ...
      },
    },
    ...
  ]
}

Supported relations: campaign

eg: .../rewards?with=campaign

Parameter Description
Supported value types string

The request example how to get specific fields of related data of rewards:

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

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "campaign_id": 5,
      "name": "Example reward name",
      ...
      campaign: {
          "id": 5,
          "name": "Example Campaign"
      },
    },
    ...
  ]
}

Get Rewards Due

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

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "reward_id": 3,
      "reward_for": "Person Referring (Direct User)",
      "reward_type": "Amazon Voucher",
      "reward_when_referral": "converted",
      "reward_value": 50,
      "recipient_id": 7,
      "recipient_first_name": "Hakob",
      "recipient_email": "hakob@referral-factory.com",
      "total_due": 1,
      "total_value": 50,
      "status": "Due",
      "issued_at": null
    },
    ...
  ],
  "links": {
    "first": "https://referral-factory.com/api/v1/rewards/due?page=1",
    "last": "https://referral-factory.com/api/v1/rewards/due?page=3",
    "prev": null,
    "next": "https://referral-factory.com/api/v1/rewards/due?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://referral-factory.com/api/v1/rewards/due",
    "per_page": 25,
    "to": 25,
    "total": 70
  }
}

This endpoint receives the rewards that are due to be issued.

The request example how to get related data of rewards due:

  curl "https://referral-factory.com/api/v1/rewards/due" \
  -H "Authorization: Bearer your_access_key" \
  -d "with=reward" \
  -d "with=recipient"

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "reward_id": 5,
      "recipient_email": "hakob@referral-factory.com",
      ...
      reward: {
        ...,
        "campaign_id": 2,
        "name": "Example Reward",
        ...
      },
      "recipient": {
        ...
        "campaign_id": 2,
        "first_name": "Hakob",
        "email": "hakob@referral-factory.com",
        ...
      }
    },
    ...
  ]
}

Supported relations: reward, recipient

eg: .../rewards/due?with[]=reward&with[]=recipient

Parameter Description
Supported value types string

The request example how to get specific fields of related data of rewards due:

This endpoint receives the rewards that are due to be issued.

The request example how to get related data of rewards due:

  curl "https://referral-factory.com/api/v1/rewards/due" \
  -H "Authorization: Bearer your_access_key" \
  -d "with=reward" \
  -d "with=recipient" \
  -d "fields.reward=id,name" \
  -d "fields.recipient=id,first_name"

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "reward_id": 5,
      "recipient_email": "hakob@referral-factory.com",
      ...
      reward: {
        "id": 5,
        "name": "Example Reward"
      },
      "recipient": {
        "id": 2,
        "first_name": "Hakob"
      }
    },
    ...
  ]
}

Get Rewards Issued

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

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "reward_id": 3,
      "reward_for": "Person Referring (Direct User)",
      "reward_type": "Amazon Voucher",
      "reward_when_referral": "converted",
      "reward_value": 50,
      "recipient_id": 7,
      "recipient_first_name": "Hakob",
      "recipient_email": "hakob@referral-factory.com",
      "total_due": 1,
      "total_value": 50,
      "status": "Invoice Due",
      "issued_at": null
    },
    ...
  ],
  "links": {
    "first": "https://referral-factory.com/api/v1/rewards/issued?page=1",
    "last": "https://referral-factory.com/api/v1/rewards/issued?page=3",
    "prev": null,
    "next": "https://referral-factory.com/api/v1/rewards/issued?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://referral-factory.com/api/v1/rewards/issued",
    "per_page": 25,
    "to": 25,
    "total": 70
  }
}

This endpoint receives the rewards that are issued.

The request example how to get related data of rewards issued:

  curl "https://referral-factory.com/api/v1/rewards/issued" \
  -H "Authorization: Bearer your_access_key" \
  -d "with=reward" \
  -d "with=recipient"

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "reward_id": 5,
      "recipient_email": "hakob@referral-factory.com",
      ...
      reward: {
        ...,
        "campaign_id": 2,
        "name": "Example Reward",
        ...
      },
      "recipient": {
        ...
        "campaign_id": 2,
        "first_name": "Hakob",
        "email": "hakob@referral-factory.com",
        ...
      }
    },
    ...
  ]
}

Supported relations: reward, recipient

eg: .../rewards/due?with[]=reward&with[]=recipient

Parameter Description
Supported value types string

The request example how to get specific fields of related data of rewards issued:

This endpoint receives the rewards that are issued.

The request example how to get related data of rewards issued:

  curl "https://referral-factory.com/api/v1/rewards/issued" \
  -H "Authorization: Bearer your_access_key" \
  -d "with=reward" \
  -d "with=recipient" \
  -d "fields.reward=id,name" \
  -d "fields.recipient=id,first_name"

The above command returns JSON structured like this:

{
  "data": [
    ...
    {
      ...
      "reward_id": 5,
      "recipient_email": "hakob@referral-factory.com",
      ...
      reward: {
        "id": 5,
        "name": "Example Reward"
      },
      "recipient": {
        "id": 2,
        "first_name": "Hakob"
      }
    },
    ...
  ]
}

Coupons

Our API allows you to see what coupons have been issued to each user, and what coupons have been used by each user. You cannot upload coupons via the API, you must log into the dashboard to do that. There is no limit to how many coupons you can upload.

Coupon Fields

Here you can see the details of the coupon for you. Below is a table of coupon fields:

Field Type Description
id numeric The id of the coupon
name string The name of the coupon
referral_id numeric The id of the referral for a coupon
batch_id numeric The id of the batch for a coupon
issued_at date The date when coupon have been issued.
used_at date The date when coupon have been used.

Coupon Relations

  curl -G "https://referral-factory.com/api/v1/coupons/Example coupon name" \
  -H "Authorization: Bearer your_access_key"

The above command returns JSON structured like this:

{
  "data": {
      "id": 1,
      "referral_id": 5,
      "name": "Example coupon name",
      "batch_id": 1,
      "issued_at": null,
      "used_at": null,
    },
  "code": 200,
  "message": "Single Coupon Response"
}

This endpoint receives the coupon which called by it's name.

The request example how to get related data of coupon:

  curl "https://referral-factory.com/api/v1/coupons/{ENTER_COUPON_HERE}" \
  -H "Authorization: Bearer your_access_key" \
  -d "with[]=referral" \
  -d "with[]=batch" \

The above command returns JSON structured like this:

{
  "data": {
      "id": 1,
      "referral_id": 5,
      "name": "Example coupon name",
      "batch_id": 1,
      "issued_at": null,
      "used_at": null,
      "referral": {
        "id": 5,
        "campaign_id": 2,
        "qualified": false,
        "first_name": "Example Referral Name",
        "email": "example-referral@gmail.com",
        "code": "Ygbek3",
        ...
      },
      "batch": {
        "id": 1,
        "name": "Example Coupon Batch Name",
        "campaign_id": 2,
        "created_at": "2022-09-01"
      }
    },
  "code": 200,
  "message": "Single Coupon Response"
}

Supported relations: batch, referral

eg: .../coupons/Example Coupon Name?with[]=referral&with[]=batch

Parameter Description
Supported value types string

The request example how to get specific fields of related data of coupon:

  curl "https://referral-factory.com/api/v1/coupons/{ENTER_COUPON_HERE}" \
  -H "Authorization: Bearer your_access_key" \
  -d "with[]=referral" \
  -d "with[]=batch" \
  -d "fields.referral=id,first_name,email"
  -d "fields.batch=id,name"

The above command returns JSON structured like this:

{
  "data": {
      "id": 1,
      "referral_id": 5,
      "name": "Example coupon name",
      "batch_id": 1,
      "issued_at": null,
      "used_at": null,
      "referral": {
        "id": 5,
        "first_name": "Example Referral Name",
        "email": "example-referral@gmail.com",
      },
      "batch": {
        "id": 1,
        "name": "Example Coupon Batch Name",
      }
    },
}

Qualify User with coupon

  curl -P "https://referral-factory.com/api/v1/coupons/{ENTER_COUPON_HERE}/qualification" \
  -H "Authorization: Bearer your_access_key"
  -X POST \
  -d "qualified=1"

The above command returns JSON structured like this:

{
  "code": 200,
  "message": "Coupon marked as used and related user marked as qualified successfully."
}

You can use this functionality to qualify or unqualify a user in your referral campaign.

HTTP Request

POST https://referral-factory.com/api/v1/coupons/{ENTER_COUPON_HERE}/qualification

Request Parameters

Parameter Required Type Validation
qualifed YES boolean True or False (1/0)

Examples

Here are some request examples, which could help you when managing your own referral program through our API.

Get Qualified users

  curl -G "https://referral-factory.com/api/v1/users" \
  -H "Authorization: Bearer your_access_key" \
  -d "filters[0][field]=qualified_at" \
  -d "filters[0][operator]=gt" \
  -d "filters[0][value]=2021-12-31" \
  -d "filters[1][field]=qualified_at" \
  -d "filters[1][operator]=lt" \
  -d "filters[1][value]=2022-02-01"

Here is a request example on how to pull all qualified referrals through the API. A qualified referral is when a referred user has successfully converted (a conversion could be a sale, a contract signed, an account opened, etc). You can qualify your referrals manually, or using an integration, or using a script, or using our API. Read more about this here.

This example code will show you how to easily see all referred users, who have qualified in a certain time frame.

How to get all qualified users for Jan 2021:

Get Users Who Has Qualified Users

  curl -G "https://referral-factory.com/api/v1/users" \
  -H "Authorization: Bearer your_access_key" \
  -d "filters[0][field]=qualified_at" \
  -d "filters[0][operator]=gt" \
  -d "filters[0][value]=2021-12-31" \
  -d "filters[1][field]=qualified_at" \
  -d "filters[1][operator]=lt" \
  -d "filters[1][value]=2022-02-01" \
  -d "with=referrer"

Here is a request example on how to pull all users who have converted referrals. In most cases, these are the direct users who are due a reward. If a user has a converted referral, that means they referred a friend and that friend became a qualified referral. Read more about this here.

How to get all users who has qualified users for Jan 2021:

How To Add Users

How to add users to your referral campaign, and get a response back with the users referral link. You can see a list of campaign fields here

How To Send New Referred Users Out

How to send new referred users out of referral factory, this would trigger every time you got a new referred lead.

You can see more information here

How To Qualify Referred Users

How to qualify referred users when they convert, this action is important because it tells Referral Factory that one of your referrals has been successful. Read more about this here

How To Call Users That Have Rewards Due

How to call all users that are due a reward, in most cases this is because they referred a user that has now become qualified. You cannot add rewards by api, you must log into your dashboard to do that, only after can you access your rewards data via api. Read more about rewards here

How To Request All Users

Want to call all the users in your referral campaign including their data? Use this example to do that. here

Webhooks

To get new referred users sent to an endpoint in real time, please use the Webhook functionality provided by Referral Factory. To learn more about this go here. This feature is most commonly used when customers want to send their new referred leads out in real time.

You can also use Webhooks to qualify referred users when they convert. You can do this by sending the users unique code to your inbound Webhook, which you can find in the settings tab. To learn more about this go here.

You can ALSO use coupon codes to qualify referred users when they convert. If you use Referral Factory to distribute coupons to the people invited (also known as referred users), you can then send the coupons that get redeemed to your inbound Webhook, which you can find in the coupons tab. To learn more about this go here.

Qualify a specific user using the code

    curl "https://referral-factory.com/webhook/{token}/qualify" \
    -X POST \
    -d "code={code}"

The above command returns JSON structured like this:

{
    "code": 201,
    "message": "User has now been qualified."
}

This endpoint qualifies a user via their unique code. You can use this functionality to qualify the user in your referral campaign when they convert. To understand what this code is please check the 'Code' column in your users tab. To find the {token} for your endpoint please check the 'Inbound Webhook' section in your settings tab. If you don't already have an account to check these items, please create one by starting a free trial here. Required fields to qualify a user are *code

HTTP Request

POST https://referral-factory.com/webhook/{token}/qualify

Request Parameters

Parameter Required Type Validation
code YES string Code of the user

Qualify a specific user using the coupon

    curl "https://referral-factory.com/webhook/{token}/qualify" \
    -X POST \
    -d "coupon={unique_coupon}"

The above command returns JSON structured like this:

{
    "code": 201,
    "message": "User has now been qualified."
}

This endpoint qualifies a user via their unique coupon. You can use this functionality to qualify the user in your referral campaign when they use their coupon (as that would mean they convert). For this functionality to work you will first need to upload your unique coupons in the 'Coupons' tab, and then insert them into a campaign to be issued to users, to learn how our coupon feature works please read this help guide. To find the {token} for your endpoint please check your 'Coupons' tab. If you don't already have an account to check these items, please create one by starting a free trial here. Required fields to qualify a user are *coupon

HTTP Request

POST https://referral-factory.com/webhook/{token}/qualify

Request Parameters

Parameter Required Type Validation
coupon YES string Coupon name of the user

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.