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:

👉 Add new users to your campaign, and issue them with referral links. Using the API allows you to bypass step one and two of the campaign builder. You will need at least a ‘name’ and ‘email’ to add a user to your campaign so they can start referring.

👉 Send new referred users (invited users) to any endpoint using webhooks, zapier or an integration with your own CRM software (see our integrations here)

👉 Access all of your user records in real-time - this is the data you would usually see on your ‘Users’ tab when logged into Referral Factory.

👉 View, update, add or delete user records

👉 Qualify ‘referred’ users once they successfully convert (for example when they complete a desired action such as subscribing or purchasing)

👉 Get notified when a reward needs to be issued to a user (with ability to issue cash, Amazon vouchers and your own coupons via the dashboard)

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 [email protected]. 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 temporarily be blocked.

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

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: Bearer your_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

You must replace your_access_key with your personal API 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

  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"

  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"

  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

  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

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

{
  "data": [
    ...
    {
      ...
      "first_name": "John",
      "email": "[email protected]",
      ...
      campaign : {...}
    },
    ...
  ]
}

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

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

{
  "data": [
    ...
    {
      ...
      "first_name": "John",
      "email": "[email protected]",
      ...
      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

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

  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"

{
  "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"

{
  "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"

{
  "data": {
    "id": 1,
    "first_name": "John",
    "email": "[email protected]",
    "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": "[email protected]",
      ...
    },
    ...
  }
}

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

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

{
  "data": [
    ...
    {
      ...
      "first_name": "John",
      "email": "[email protected]",
      ...
      campaign: {
          ...
          "name": "Example Campaign",
          ...
      }
    },
    ...
  ]
}

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

  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"

{
  "data": [
    ...
    {
      ...
      "first_name": "John",
      "email": "[email protected]",
      ...
      campaign: {
          ...
          "name": "Example Campaign",
          ...
      },
      referrer: {
          ...
          "first_name": "James",
          "email": "[email protected]",
          ...
      },
      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"

{
  "data": [
    {
          ...
          "first_name": "John",
          "email": "[email protected]",
          ...
    },
    ...
  ],
  "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"

{
  "data": {
    ...
    "first_name": "John",
    "email": "[email protected]",
    "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": "[email protected]",
        "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": "[email protected]",
        "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 protected]"

{
    "data": {
          "id": 1,
          "first_name": "John",
          "email": "[email protected]",
          "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": "[email protected]",
              ...
          },
    },
    "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.

When you create a new user, you may send through the notify property in the request. Sending the notify property in the request will trigger the 'First email notification' for the person referring. Please note: For the notify property to work - This email must be enabled and created in the campaign settings (not via the API), Read more about these notifications here.

Update a Specific User

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

{
  "data": {
        "id": 1,
        "first_name": "John",
        "email": "[email protected]",
        "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": "[email protected]",
          ...
        },
  },
    "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

Update Qualification a Specific User by Email and Campaign Id

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

{
  "data": {
        ...
        "first_name": "John",
        "email": "[email protected]",
        "campaign_id": 25,
        "qualified": true,
        "qualified_at": "2023-12-04T12:35:17.000000Z",
        "code": "{random-code}",
        ...
  },
    "code": 200,
    "message": "User's qualification 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/qualification

Request Parameters

Parameter	Required	Type	Validation
email	Yes	string	The email of a user
campaign_id	Yes	numeric	The id of the campaign user
qualified	Yes	boolean	The property should let us know if user qualified or not

Delete a Specific User

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

{
    "data": {
          ...
          "campaign_id": 1,
          "qualified": true,
          "first_name": "John",
          "email": "[email protected]",
          ...
    },
    "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"

{
  "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.

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

{
  "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`

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

{
  "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"

{
  "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": "[email protected]",
      "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.

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

{
  "data": [
    ...
    {
      ...
      "reward_id": 5,
      "recipient_email": "[email protected]",
      ...
      reward: {
        ...,
        "campaign_id": 2,
        "name": "Example Reward",
        ...
      },
      "recipient": {
        ...
        "campaign_id": 2,
        "first_name": "Hakob",
        "email": "[email protected]",
        ...
      }
    },
    ...
  ]
}

Supported relations: reward, recipient

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

Parameter	Description
Supported value types	`string`

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

  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"

{
  "data": [
    ...
    {
      ...
      "reward_id": 5,
      "recipient_email": "[email protected]",
      ...
      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"

{
  "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": "[email protected]",
      "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.

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

{
  "data": [
    ...
    {
      ...
      "reward_id": 5,
      "recipient_email": "[email protected]",
      ...
      reward: {
        ...,
        "campaign_id": 2,
        "name": "Example Reward",
        ...
      },
      "recipient": {
        ...
        "campaign_id": 2,
        "first_name": "Hakob",
        "email": "[email protected]",
        ...
      }
    },
    ...
  ]
}

Supported relations: reward, recipient

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

Parameter	Description
Supported value types	`string`

This endpoint receives the rewards that are 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"

{
  "data": [
    ...
    {
      ...
      "reward_id": 5,
      "recipient_email": "[email protected]",
      ...
      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"

{
  "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.

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

{
  "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": "[email protected]",
        "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`

  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"

{
  "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": "[email protected]",
      },
      "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"

{
  "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.

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 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}"

{
    "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}"

{
    "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

    {
        "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.