Add Referral Code Holders

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/referrals/members/{memberId}/holders \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "holders": [
    {
      "source_id": "cst-prsn01",
      "name": "Alex Doe",
      "email": "alex-doe@your.domain.com",
      "country": "England"
    },
    {
      "source_id": "cst-prsn02",
      "name": "Alex Joe",
      "email": "alex-joe@your.domain.com",
      "country": "Wales"
    }
  ],
  "metadata": {
    "influencer_code": true
  }
}
'

{
  "holders": [
    {
      "id": "rh_0f198761748966ffab",
      "created_at": "2024-07-23T10:40:48.579Z",
      "redeemable_id": "v_uOrG9tQresN9X51gbAoo0a2vY4MLV9lS",
      "redeemable_object": "voucher",
      "campaign_id": "camp_vVk4unz3k4gA023fk9XoSiTh",
      "campaign_type": "REFERRAL_PROGRAM",
      "voucher_type": "DISCOUNT_VOUCHER",
      "customer_id": "cust_r8yoJtgAAF2pqU1yuICtk9bv",
      "holder_role": "REFEREE",
      "object": "redeemable_holder",
      "metadata": {
        "influencer_code": true
      }
    },
    {
      "id": "rh_0f198761748966ffac",
      "created_at": "2024-07-23T10:40:48.579Z",
      "redeemable_id": "v_uOrG9tQresN9X51gbAoo0a2vY4MLV9lS",
      "redeemable_object": "voucher",
      "campaign_id": "camp_vVk4unz3k4gA023fk9XoSiTh",
      "campaign_type": "REFERRAL_PROGRAM",
      "voucher_type": "DISCOUNT_VOUCHER",
      "customer_id": "cust_uCLPtbQkQayw6t40O9IMPQzV",
      "holder_role": "REFEREE",
      "object": "redeemable_holder",
      "metadata": {
        "influencer_code": true
      }
    }
  ]
}

Add Referral Code Holders

Adds new holders to a referral code as referees. The data sent in the request is upserted into the customer data.

If the request returns an error even for one customer, you have to resend the whole request. Customer data is upserted if the data for all customers is correct.

To use this endpoint, you must have the following permissions:

Create and modify Customers and Segments (customers.modify)
Publish Voucher (vouchers.publish)

👍 To add a holder as a referrer, use the Create Publication endpoint.

📘 Alternative endpoint

This endpoint is an alternative to the Add Referral Code Holders endpoint. The URL was re-designed to retrieve the referral member holders without providing the campaignId as a path paremeter.

POST

referrals

members

{memberId}

holders

Add Referral Code Holders

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/referrals/members/{memberId}/holders \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "holders": [
    {
      "source_id": "cst-prsn01",
      "name": "Alex Doe",
      "email": "alex-doe@your.domain.com",
      "country": "England"
    },
    {
      "source_id": "cst-prsn02",
      "name": "Alex Joe",
      "email": "alex-joe@your.domain.com",
      "country": "Wales"
    }
  ],
  "metadata": {
    "influencer_code": true
  }
}
'

{
  "holders": [
    {
      "id": "rh_0f198761748966ffab",
      "created_at": "2024-07-23T10:40:48.579Z",
      "redeemable_id": "v_uOrG9tQresN9X51gbAoo0a2vY4MLV9lS",
      "redeemable_object": "voucher",
      "campaign_id": "camp_vVk4unz3k4gA023fk9XoSiTh",
      "campaign_type": "REFERRAL_PROGRAM",
      "voucher_type": "DISCOUNT_VOUCHER",
      "customer_id": "cust_r8yoJtgAAF2pqU1yuICtk9bv",
      "holder_role": "REFEREE",
      "object": "redeemable_holder",
      "metadata": {
        "influencer_code": true
      }
    },
    {
      "id": "rh_0f198761748966ffac",
      "created_at": "2024-07-23T10:40:48.579Z",
      "redeemable_id": "v_uOrG9tQresN9X51gbAoo0a2vY4MLV9lS",
      "redeemable_object": "voucher",
      "campaign_id": "camp_vVk4unz3k4gA023fk9XoSiTh",
      "campaign_type": "REFERRAL_PROGRAM",
      "voucher_type": "DISCOUNT_VOUCHER",
      "customer_id": "cust_uCLPtbQkQayw6t40O9IMPQzV",
      "holder_role": "REFEREE",
      "object": "redeemable_holder",
      "metadata": {
        "influencer_code": true
      }
    }
  ]
}

Authorizations

X-App-Id

string

header

required

X-App-Token

string

header

required

Path Parameters

memberId

string

required

Unique referral code or its identifier.

Example:

"MmFAzfDe"

Body

application/json

Specify the customer data to be upserted as redeemable holders.

Request body schema for POST v1/referrals/{campaignId}/members/{memberId}/holders and POST v1/referrals/members/{memberId}/holders.

holders

Customer · object[]

required

Array of holders to be added to a referral card as referees. You have to send at least one object in the array up to a maximum of 100 objects. You can send either a source_id or id, or both; however, at least one of them is required. If both are sent, Voucherify checks id to upsert that customer's data.

Show child attributes

metadata

object

A set of custom key/value pairs that you can attach to the redeemable holders sent in the array. The value can be a string, number, boolean, date, datetime, image URL, or object. The metadata must meet the metadata schema for publications. The metadata object stores all custom attributes assigned to the redeemable holder.

Response

Returns a list of redeemable holder objects.

Response body schema for POST v1/referrals/{campaignId}/members/{memberId}/holders and POST v1/referrals/members/{memberId}/holders.

holders

Customer Redeemable · object[]

required

Contains an array of referral card holders who are the customers sent in the request.

Show child attributes

Last modified on February 3, 2026

Add Referral Code Holders with Campaign ID Remove Referral Card Holder with campaign ID

⌘I