ReferralHero
ReferralHero
Login/Signup
Pricing
Examples
Welcome
Common Questions
Features
Integrations
Confirmation Email
Automations
Security
Misc
Integrate
Embeddable Widgets
Platform-specific Instructions
Javascript Web API
REST API
Errors
Webhooks
Objects
Endpoint Reference
Powered by GitBook

Endpoint Reference

Lists

get
Retrieve all lists

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.
Request
Response
Request
Path Parameters
api_token
required
string
Your API Token.
page
optional
string
Page you want to jump to. By default 1.
Response
200: OK
{
  "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
}

post
Create a new list

https://app.referralhero.com/api/v2/lists
Create a new list/campaign in your account.
Request
Response
Request
Path Parameters
website
optional
string
Default Referral URL
name
required
string
Your list name
api_token
required
string
Your API Token
Response
200: OK
{
  "status": "ok",
  "data": {
    < List object >
  },
  "calls_left": 1000,
  "timestamp": 1487659010
}

get
Get List Leaderboard

https://app.referralhero.com/api/v2/lists/:uuid/leaderboard
Retrieve leaderboard of the top 10 subscribers in a list.
Request
Response
Request
Path Parameters
uuid
required
string
Your list UUID
api_token
required
string
Your API Token
Response
200: OK
{
  "status": "ok",
  "data": {
    "ranking": [
      {
        < Subscriber object >
      },
      {
        < Subscriber object >
      },
      ...
    ]
  },
  "calls_left": 1000,
  "timestamp": 1487659347
}

get
Get list rewards

https://app.referralhero.com/api/v2/lists/:uuid/bonuses
Retrieve list of rewards from a list.
Request
Response
Request
Path Parameters
uuid
required
string
Your list UUID
api_token
required
string
Your API Token
Response
200: OK
{
  "status": "ok",
  "data": [
    {
      < Reward object >
    },
    {
      < Reward object >
    }
  ],
  "calls_left": 1000,
  "timestamp": 1487659708
}

Subscribers

get
Retrieve all subscribers from a list

https://app.referralhero.com/api/v2/lists/:uuid/subscribers
Get all the subscribers in a list. Results are paginated (max 50 results per page).
Request
Response
Request
Path Parameters
sort_by
optional
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
optional
string
Page you want to jump to. By default 1.
uuid
required
string
Your list UUID
api_token
required
string
Your API Token
Response
200: OK
{
  "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
}

post
Create a new subscribers

https://app.referralhero.com/api/v2/lists/:uuid/subscribers
Request
Response
Request
Path Parameters
transaction_id
optional
string
The unique ID of the transaction. Useful when tracking referrals for purchases.
conversion_category
optional
string
The type of referral. Useful for creating reports.
conversion_value
optional
number
The monetary value of the referral.
device
optional
string
The device used by the subscriber to sign up. Used for analytics.
source
optional
string
The source of the subscriber. Used for analytics.
double_optin
optional
boolean
If set to false the subscriber will not received a confirmation email.
points
optional
integer
The number of points for the subscriber. It only works for "contest" campaigns.
referrer
optional
string
Set a referrer for the subscriber by providing the referrer's referral code or email.
extra_field_2
optional
string
The extra field 2 of the subscriber
extra_field
optional
string
The extra field of the subscriber
name
optional
string
The name of the subscriber
api_token
required
string
Your API Token
uuid
required
string
The list uuid
email
required
string
The email of the subscriber
domain
required
string
The URL for the referral link
Response
200: OK
{
  "status": "ok",
  "data": {
    "response": "subscriber_created",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

get
Retrieve subscriber by ID

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.
Request
Response
Request
Path Parameters
Your API Token
required
string
Your API Token
uuid
required
string
The list UUID
subscriber_id
required
string
The ID of the subscriber
Response
200: OK
{
  "status": "ok",
  "data": {
    "response": "subscriber_retrieved",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487676070
}

get
Retrieve subscriber by email

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.
Request
Response
Request
Path Parameters
api_token
required
string
Your API Token
uuid
required
string
The list UUID
email
required
string
The email of the subscriber.
Response
200: OK
{
  "status": "ok",
  "data": {
    "response": "subscriber_retrieved",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487676070
}

post
Update a subscriber

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.
Request
Response
Request
Path Parameters
points
optional
string
The number of points of the subscriber. It only works for "contest" campaigns.
email
optional
string
The email of the subscriber
extra_field_2
optional
string
The extra field 2 of the subscriber
extra_field
optional
string
The extra field of the subscriber
name
optional
string
The name of the subscriber
api_token
required
string
Your API Token
uuid
required
string
The list UUID
subscriber_id
required
string
The ID of the subscriber
Response
200: OK
{
  "status": "ok",
  "data": {
    "response": "subscriber_updated",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

post
Confirm referral

https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/confirm
Confirm a referral. Useful when your campaign has enabled the "Manual confirmation" option and you want to confirm referrals when a specific event occur (e.g: upgrade to a paid plan, end of trial, etc) Note: only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a subscriber_not_found error.
Request
Response
Request
Path Parameters
api_token
required
string
Your API Token
uuid
required
string
Your list UUID
subscriber_id
required
string
The ID of the subscriber
Response
200: OK
{
  "status": "ok",
  "data": {
    "response": "subscriber_confirmed",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

post
Promote a subscriber

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.
Request
Response
Request
Path Parameters
api_token
required
string
Your API Token
uuid
required
string
Your list UUID
subscriber_id
required
string
The ID of the subscriber
Response
200: OK
{
  "status": "ok",
  "data": {
    "response": "subscriber_promoted",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

get
Retrieve all referrals of a subscriber

https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/referred
Retrieve all referrals of a single subscriber. Results are paginated (max 50 results per page).
Request
Response
Request
Path Parameters
api_token
required
string
Your API Token
uuid
required
string
Your list UUID
subscriber_id
required
string
The ID of the subscriber.
page
optional
string
Page you want to jump to. By default is 1.
sort_by
optional
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
Response
200: OK
{
  "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
}

delete
Delete a subscriber

https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id
Delete a single subscriber.
Request
Response
Request
Path Parameters
api_token
required
string
Your API Token
uuid
required
string
The list UUID
subscriber_id
required
string
The ID of the subscriber
Response
200: OK
{
  "status": "ok",
  "data": {
    "response": "subscriber_deleted",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}
Previous
Objects
Last updated 2 weeks ago
Contents
Lists
get
Retrieve all lists
post
Create a new list
get
Get List Leaderboard
get
Get list rewards
Subscribers
get
Retrieve all subscribers from a list
post
Create a new subscribers
get
Retrieve subscriber by ID
get
Retrieve subscriber by email
post
Update a subscriber
post
Confirm referral
post
Promote a subscriber
get
Retrieve all referrals of a subscriber
delete
Delete a subscriber