Endpoint Reference

Lists

Locations where you can find most of the required parameters:

Path Parameters

Location

api_token

ReferralHero dashboard > Account > API

name

ReferralHero dashboard > Campaign name

uuid

ReferralHero dashboard > Campaign > Installation > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. MF078d000987

Create a new list

POST https://app.referralhero.com/api/v2/lists

Create a new list/campaign in your account.

Path Parameters

Name
Type
Description

website

string

Default Referral URL

name

string

Your list name

api_token

string

Your API Token

{
  "status": "ok",
  "data": {
    < List object >
  },
  "calls_left": 1000,
  "timestamp": 1487659010
}

Retrieve all lists

GET https://app.referralhero.com/api/v2/lists

Get all the lists/campaigns in your account. Results are paginated (10 results per page). Only active lists will be retrieved.

Path Parameters

Name
Type
Description

api_token

string

Your API Token.

page

string

Page you want to jump to. By default 1.

{
  "status": "ok",
  "data": {
    "response": "lists_retrieved",
    "lists": [
      {
        < List object >
      },
      {
        < List object >
      },
      ...
    ],
    "pagination": {
      "total_pages": 7,
      "current_page": 1,
      "per_page": 10,
      "total_objects": 67
    }
  },
  "calls_left": 1000,
  "timestamp": 1487658324
}

Get List Leaderboard

GET https://app.referralhero.com/api/v2/lists/:uuid/leaderboard

Retrieve leaderboard of the top 10-100 subscribers in a list.

Path Parameters

Name
Type
Description

uuid

string

Your list UUID

api_token

string

Your API Token

count

string

Number (10-100) of subscribers returned in the leaderboard

{
  "status": "ok",
  "data": {
    "ranking": [
      {
        < Subscriber object >
      },
      {
        < Subscriber object >
      },
      ...
    ]
  },
  "calls_left": 1000,
  "timestamp": 1487659347
}

Get list rewards

GET https://app.referralhero.com/api/v2/lists/:uuid/bonuses

Retrieve list of rewards from a list.

Path Parameters

Name
Type
Description

uuid

string

Your list UUID

api_token

string

Your API Token

{
  "status": "ok",
  "data": [
    {
      < Reward object >
    },
    {
      < Reward object >
    }
  ],
  "calls_left": 1000,
  "timestamp": 1487659708
}

Subscribers

Locations where you can find most of the required parameters:

Path Parameters

Location

api_token

ReferralHero dashboard > Account > API

uuid

ReferralHero dashboard > Campaign Overview> Edit Campaign > Launch > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. MF078d000987

email

The email of the subscriber

domain

ReferralHero dashboard > Campaign > Options > Default Referral Link

subscriber_id

ReferralHero dashboard > Campaign > Subscribers

Add a subscriber

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers

Path Parameters

Name
Type
Description

transaction_id

string

The unique ID of the transaction. Useful when tracking referrals for purchases.

conversion_category

string

The type of subscriber. Useful for creating reports or segmenting subscribers.

conversion_value

number

The monetary value of the referral.

device

string

The device used by the subscriber to sign up. Used for analytics.

source

string

The source of the subscriber. Used for analytics.

double_optin

boolean

If set to false the subscriber will not received a confirmation email.

points

integer

The number of points for the subscriber. It only works for "contest" campaigns.

referrer

string

Set a referrer for the subscriber by providing the referrer's referral code or email.

extra_field_2

string

The extra field 2 of the subscriber

extra_field

string

The extra field of the subscriber

name

string

The name of the subscriber

api_token

string

Your API Token

uuid

string

The list uuid

email

string

The email of the subscriber

domain

string

The URL for the referral link

status

string

Use 'custom_event_pending' to set the referral status to pending

stripe_customer_id

string

Stripe Customer ID

{
  "status": "ok",
  "data": {
    "response": "subscriber_created",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Note for Web Integrations:

When deciding between using our Javascript Web API or REST API to interact with ReferralHero, it is generally advisable to 'add a subscriber' using the Javascript Web API as you will take advantage of our powerful global tracking script and cookie. Once a subscriber is added to our database, you can manage that subscriber and campaign more freely using either the Javascript Web API or REST API.

Track referral conversion event

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/track_referral_conversion_event

Use when your Campaign Goal is set to track two or three conversion events.

If the referrer is present in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, we will create the referral and set the referral status.

If the referrer is not present in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, the referral will not be created.

The Referral Status Is Set To:

Confirmed (if tracking two conversion events)

Unconfirmed (if tracking three conversion events)

Note:

1. Your campaign Goal must be set up to track two or three conversion events otherwise, an error will return.

2. If the referral is present in ReferralHero with pending status, a successful response custom_event_completed will return.

3. If the referral unique identifier is not present in the ReferralHero, but the referrer unique identifier is present, a successful response custom_event_completed with the data of the new confirmed referral will return.

4. If a referral exists but the referral status is not pending, the error custom event is already completed will return.

5. If the referral unique identifier is not present in ReferralHero and the referrer is also not provided in the API, the error referrer is invalid or not present will return.

6. If the referral status is unconfirmed or confirmed, the error custom event is already completed will return.

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

email

string

The email of subscriber (if unique identifier)

referrer

string

The unique identifier of the referrer

phone_number

string

The phone number of subscriber (if unique identifier)

crypto_wallet_address

string

The crypto wallet address of subscriber (if unique identifier)

conversion_value

string

Referral conversion value

stripe_customer_id

string

Stripe Customer ID

{
  "status": "ok",
  "data": {
    "response": "custom_event_completed",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Confirm referral by Subscriber ID

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/confirm

Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc).

The Referral Status Is Set To:

Confirmed (if tracking three conversion events)

Note:

1. Your campaign Goal must be set up to track three conversion events otherwise, an error will return.

2. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a subscriber_not_found error.

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

subscriber_id

string

The ID of the subscriber

{
  "status": "ok",
  "data": {
    "response": "subscriber_confirmed",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Confirm referral by Unique Identifier

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/confirm

Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc).

The Referral Status Is Set To:

Confirmed (if tracking three conversion events)

Note:

1. Your campaign Goal must be set up to track three conversion events otherwise, an error will return.

2. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a subscriber_not_found error.

Path Parameters

Name
Type
Description

api_token

String

Your API Token

uuid

String

Your list UUID

email

String

If email is the Unique Identifier

crypto_wallet_address

String

If crypto_wallet_address is the Unique Identifier

phone_number

String

if phone_number is the Unique Identifier

{
  "status": "ok",
  "data": {
    "response": "subscriber_confirmed",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Update a subscriber

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id

Update a single subscriber. Note: only verified subscribers can be updated. Trying to update a non-verified subscriber will return a subscriber_not_found error.

Path Parameters

Name
Type
Description

points

string

The number of points of the subscriber. It only works for "contest" campaigns.

email

string

The email of the subscriber

extra_field_2

string

The extra field 2 of the subscriber

extra_field

string

The extra field of the subscriber

name

string

The name of the subscriber

api_token

string

Your API Token

uuid

string

The list UUID

subscriber_id

string

The ID of the subscriber

stripe_customer_id

string

Stripe Customer ID

{
  "status": "ok",
  "data": {
    "response": "subscriber_updated",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Add points to a subscriber

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_points

Add points to an existing subscriber for any reason. Note: Trying to add points to a non-existing subscriber will return a subscriber_not_found error.

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

email

string

The email of subscriber (if unique identifier)

phone_number

string

The phone number of subscriber (if unique identifier)

crypto_wallet_address

string

The crypto wallet address of subscriber (if unique identifier)

points

string

The number or points to add

{
  "status": "ok",
  "data": {
    "response": "points_added",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Track Transactions

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_transactions

This allows you to pass transaction data to ReferralHero.

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

email

string

The email of subscriber (if unique identifier)

phone_number

string

The phone number of subscriber (if unique identifier)

crypto_wallet_address

string

The crypto wallet address of subscriber (if unique identifier)

amount (required)

string

Amount of the Transaction

transaction_id

string

Transaction ID

product_id

string

Product ID

lifetime_spend

string

Total lifetime spend

Response

{
    "status": "ok",
    "data": {
        "id": 592,
        "transaction_id": "MFa19e08789720240219142611",
        "transaction_time": "2024-02-19T14:26:11.000Z",
        "amount": 56665,
        "product_id": "12345",
        "response": "transaction_added"
    },
    "calls_left": null,
    "timestamp": 1708352775
}

Promote a subscriber

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/promote

Promote a single subscriber. Read this article about what "promoting" means. Note: only verified subscribers can be promoted. Trying to promote a non-verified subscriber will return a subscriber_not_found error.

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

subscriber_id

string

The ID of the subscriber

{
  "status": "ok",
  "data": {
    "response": "subscriber_promoted",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Trigger manual rewards

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/unlock_promoted_reward

Used to trigger the Rewards for Promoted Winners

Path Parameters

Name
Type
Description

api_token

String

Your API Token

uuid

String

Your list UUID

subscriber_id

String

The ID of the subscriber

reward_id

String

The ID of the promotion reward

{
    "response": "reward_unlocked",
    "reward": {
        "id": 203,
        "title": "Winner 2",
        "header": null,
        "description": "",
        "referrals": null,
        "image": "/missing.png",
        "label": "Winner Reward",
        "points": null,
        "category": "promoted_winners"
    }
}

Retrieve all subscribers from a list

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers

Get all the subscribers in a list. Results are paginated (max 50 results per page).

Path Parameters

Name
Type
Description

sort_by

string

Sort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc , people_referred_asc, people_referred_desc, points_asc, points_desc

page

string

Page you want to jump to. By default 1.

uuid

string

Your list UUID

api_token

string

Your API Token

extra_field

string

The extra field of the subscriber

extra_field_2

string

The extra field 2 of the subscriber

option_field

string

The option field of the subscriber

stripe_customer_id

string

Stripe Customer ID

{
  "status": "ok",
  "data": {
    "response": "subscribers_retrieved",
    "subscribers": [
      {
        < Subscriber object >
      },
      {
        < Subscriber object >
      },
      ...
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 50,
      "total_objects": 14
    }
  },
  "calls_left": 1000,
  "timestamp": 1487675505
}

Retrieve subscriber by ID

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id

Retrieve a single subscriber. Note: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a subscriber_not_found error.

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

The list UUID

subscriber_id

string

The ID of the subscriber

{
  "status": "ok",
  "data": {
    "response": "subscriber_retrieved",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487676070
}

Retrieve subscriber by email

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_email

Retrieve a single subscriber. Note: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a subscriber_not_found error.

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

The list UUID

email

string

The email of the subscriber.

{
  "status": "ok",
  "data": {
    "response": "subscriber_retrieved",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487676070
}

Retrieve subscriber by MWR

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_mwr

Retrieve a single subscriber. Note: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a subscriber_not_found error.

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

The list UUID

mwr

string

The referrer's referral code

{
  "status": "ok",
  "data": {
    "response": "subscriber_retrieved",
    < Subscriber object >
  },
  "calls_left": null,
  "timestamp": 1725032082
}

Retrieve all referrals (pending, unconfirmed, confirmed) of a subscriber

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/referred

Retrieve all referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page).

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

subscriber_id

string

The ID of the subscriber.

page

string

Page you want to jump to. By default is 1.

sort_by

string

Sort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc

{
  "status": "ok",
  "data": {
    "response": "subscribers_retrieved",
    "subscribers": [
      {
        < Subscriber object >
      },
      {
        < Subscriber object >
      },
      ...
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 50,
      "total_objects": 14
    }
  },
  "calls_left": 1000,
  "timestamp": 1487675505
}

Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a subscriber

GEThttps://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_all_referrals

Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page).

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

subscriber_id

string

The ID of the subscriber.

{
    "status": "ok",
    "data": {
        "response": "subscribers_retrieved",
        "subscribers": [
            {
                < Subscriber object >
                ,
                "pending_referrals": 0,
                "unconfirmed_referrals": 0,
                "people_referred": 0,
                "level_2_confirmed_referrals": 0,
                "level_3_confirmed_referrals": 0,
                "promoted": false,
                "promoted_at": null,
                "verified": true,
                "verified_at": 1723452705,
                "points": 0,
                "risk_level": 0,
                "host": "https://www.sagicor.bank/refer",
                "source": null,
                "device": null,
                "referral_link": "https://www.sagicor.bank/refer?mwr=eb134b6d",
                "created_at": 1723452705,
                "last_updated_at": 1723452705,
                "referral_status": "confirmed",
                "referral_status_at": 1723452705,
                "universal_link": "https://app.referralhero.com//MF0b793ba17d/universal_link?mwr=eb134b6d"
            }
        ],
        "pagination": {
            "total_pages": 1,
            "current_page": 1,
            "per_page": 50,
            "total_objects": 1
        }
    },
    "calls_left": null,
    "timestamp": 1723457099
}

Retrieve all Level 3 referrals (pending, unconfirmed, confirmed) of a subscriber

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_all_referrals

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

subscriber_id

string

The ID of the subscriber.

{
    "status": "ok",
    "data": {
        "response": "subscribers_retrieved",
        "subscribers": [
            {
                < Subscriber object >
                ,
                "pending_referrals": 0,
                "unconfirmed_referrals": 0,
                "people_referred": 0,
                "level_2_confirmed_referrals": 0,
                "level_3_confirmed_referrals": 0,
                "promoted": false,
                "promoted_at": null,
                "verified": true,
                "verified_at": 1723452705,
                "points": 0,
                "risk_level": 0,
                "host": "https://www.sagicor.bank/refer",
                "source": null,
                "device": null,
                "referral_link": "https://www.sagicor.bank/refer?mwr=eb134b6d",
                "created_at": 1723452705,
                "last_updated_at": 1723452705,
                "referral_status": "confirmed",
                "referral_status_at": 1723452705,
                "universal_link": "https://app.referralhero.com//MF0b793ba17d/universal_link?mwr=eb134b6d"
            }
        ],
        "pagination": {
            "total_pages": 1,
            "current_page": 1,
            "per_page": 50,
            "total_objects": 1
        }
    },
    "calls_left": null,
    "timestamp": 1723457099
}

Retrieve all level 1 confirmed referrals of a subscriber

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_1_referrals

Retrieve all level 1 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page).

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

subscriber_id

string

The ID of the subscriber.

page

string

Page you want to jump to. By default is 1.

sort_by

string

Sort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc

{
  "status": "ok",
  "data": {
    "response": "subscribers_retrieved",
    "subscribers": [
      {
        < Subscriber object >
      },
      {
        < Subscriber object >
      },
      ...
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 50,
      "total_objects": 14
    }
  },
  "calls_left": 1000,
  "timestamp": 1487675505
}

Retrieve all level 2 confirmed referrals of a subscriber

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_referrals

Retrieve all level 2 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page).

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

subscriber_id

string

The ID of the subscriber.

page

string

Page you want to jump to. By default is 1.

sort_by

string

Sort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc

{
  "status": "ok",
  "data": {
    "response": "subscribers_retrieved",
    "subscribers": [
      {
        < Subscriber object >
      },
      {
        < Subscriber object >
      },
      ...
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 50,
      "total_objects": 14
    }
  },
  "calls_left": 1000,
  "timestamp": 1487675505
}

Retrieve all level 3 confirmed referrals of a subscriber

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_referrals

Retrieve all level 3 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page).

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

Your list UUID

subscriber_id

string

The ID of the subscriber.

page

string

Page you want to jump to. By default is 1.

sort_by

string

Sort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc

{
  "status": "ok",
  "data": {
    "response": "subscribers_retrieved",
    "subscribers": [
      {
        < Subscriber object >
      },
      {
        < Subscriber object >
      },
      ...
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 50,
      "total_objects": 14
    }
  },
  "calls_left": 1000,
  "timestamp": 1487675505
}

Retrieve all rewards unlocked by a subscriber

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/rewards

Get all rewards unlocked by the subscriber. Results are paginated (max 50 results per page).

Path Parameters

Name
Type
Description

api_token

String

Your API Token

uuid

String

Your list UUID

subscriber_id

String

The ID of the subscriber

status (optional)

String

Status of the reward (i.e. sent , resent , canceled , pending or flagged)

{
    "status": "ok",
    "data": {
        "response": "rewards_retrieved",
        "rewards": [
            {
                "id": 214,
                "name": "10% commission",
                "status": "sent",
                "referrals": 1,
                "created_at": 1729166882,
                "unlocked_date": "2024-10-17",
                "sent_date": "2024-10-17",
                "referral": "nishchay@referralhero.com",
                "value": 100.0,
                "total": "",
                "signup_type": null,
                "referrals_type": "confirmed",
                "recurring_count": null,
                "coupon_code": null,
                "coupon_group": null,
                "image_url": null
            },
        ],
        "pagination": {
            "total_pages": 1,
            "current_page": 1,
            "per_page": 10,
            "total_objects": 1
        }
    },
    "calls_left": null,
    "timestamp": 1729186260
}

Delete a subscriber

DELETE https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id

Delete a single subscriber.

Path Parameters

Name
Type
Description

api_token

string

Your API Token

uuid

string

The list UUID

subscriber_id

string

The ID of the subscriber

{
  "status": "ok",
  "data": {
    "response": "subscriber_deleted",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Update reward status by reward_id

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/update_reward_status

Update status of an unlocked reward of a subscriber by reward_id

Path Parameters

Name
Type
Description

api_token

String

Your API Token

uuid

String

Your list UUID

reward_id

String

ID of reward provided in GET all rewards unlocked by a subscriber API

status

String

sent/resent/canceled

{
  "status": "ok",
  "data": {
    "id": 1795,
    "name": "A free Premium account for 1 year",
    "status": "confirmed",
    "referrals": null,
    "created_at": 1686397951,
    "signup_type": "organic subscriber",
    "referrals_type": null,
    "recurring_count": null
  },
  "calls_left": null,
  "timestamp": 1686561403
}

Create coupon group

POST https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups

Add new coupon group

Path Parameters

Name
Type
Description

api_token

String

Your API Token

uuid

String

Your list UUID

name

String

Coupon group name

coupons

String

Array, e.g. ["ab23fg, fghg45, gh78wl"]

active

String

True or false

{
  "status": "ok",
  "data": {
    "id": "rh400",
    "name": "RH400",
    "active": true,
    "created_at": 1686563261,
    "coupons": [],
    "response": "coupon_group_created"
  },
  "calls_left": null,
  "timestamp": 1686563261
}

Create coupons

POST https://app.referralhero.com/api/v2/lists/:uuid/coupons

Add coupon(s) to a coupon group

Path Parameters

Name
Type
Description

api_token

String

Your API Token

uuid

String

Your list UUID

coupon_group_id

String

ID of coupon group

coupons

String

Array, e.g. ["ab23fg", fghg45”, “gh78wl"]

{
  "status": "ok",
  "data": {
    "id": "rh200",
    "name": "RH200",
    "active": true,
    "created_at": 1686563246,
    "coupons": [
      {
        "code": "FCMPFI",
        "available": true,
        "sent_at": null,
        "email_id": null,
        "created_at": 1686563246
      },
      {
        "code": "U3EHFD",
        "available": true,
        "sent_at": null,
        "email_id": null,
        "created_at": 1686563246
      },
      {
        "code": "tvt4g45v",
        "available": true,
        "sent_at": null,
        "email_id": null,
        "created_at": 1686563246
      },
      {
        "code": "RFGH677",
        "available": true,
        "sent_at": null,
        "email_id": null,
        "created_at": 1686563246
      },
      {
        "code": "KMLFG767",
        "available": true,
        "sent_at": null,
        "email_id": null,
        "created_at": 1686563246
      }
    ]
  },
  "calls_left": null,
  "timestamp": 1686676359
}

Retrieve all coupon groups

GET https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups

Get all coupon groups of a campaign

Path Parameters

Name
Type
Description

api_token

String

Your API Token

uuid

String

Your list UUID

{
  "status": "ok",
  "data": {
    "response": "coupon_groups_retrieved",
    "coupon_groups": [
      {
        "id": "rh200",
        "name": "RH200",
        "active": true,
        "created_at": 1686563246,
        "coupons": [
          {
            "code": "FCMPFI",
            "available": true,
            "sent_at": null,
            "email_id": null,
            "created_at": 1686563246
          },
          {
            "code": "U3EHFD",
            "available": true,
            "sent_at": null,
            "email_id": null,
            "created_at": 1686563246
          }
        ]
      },
      {
        "id": "rh400",
        "name": "RH400",
        "active": true,
        "created_at": 1686563261,
        "coupons": []
      }
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 50,
      "total_objects": 2
    }
  },
  "calls_left": null,
  "timestamp": 1686563777
}

Retrieve coupons

GET https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups/:id

Get all coupons within a coupon group

Path Parameters

Name
Type
Description

api_token

String

Your API Token

uuid

String

Your list UUID

id

String

ID of coupon group

{
  "status": "ok",
  "data": {
    "id": "rh200",
    "name": "RH200",
    "active": true,
    "created_at": 1686563246,
    "coupons": []
  },
  "calls_left": null,
  "timestamp": 1686563407
}
PreviousObjectsNextMobile SDKs

Last updated