Add Referral Code Holders

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/referrals/members/{memberId}/holders \
  --header 'Authorization: Bearer <token>' \
  --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 'Authorization: Bearer <token>' \
  --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

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

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

holders.id

string

The ID of an existing customer.

holders.source_id

string

A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored.

holders.name

string

Customer's first and last name.

holders.description

string

An arbitrary string that you can attach to a customer object.

holders.email

string

Customer's email address.

holders.phone

string

Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.

holders.birthday

string<date>

Deprecated. ~~Customer's birthdate; format YYYY-MM-DD~~.

holders.birthdate

string<date>

Customer's birthdate; format YYYY-MM-DD.

holders.address

object

Customer's address.

Show child attributes

holders.address.city

string

City

holders.address.state

string

State

holders.address.line_1

string

First line of address.

holders.address.line_2

string

Second line of address.

holders.address.country

string

Country.

holders.address.postal_code

string

Postal code.

holders.metadata

object

A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments.

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

holders.id

string

required

Unique identifier of the redeemable holder.

Example:

"rh_0e7b8db4700106a852"

holders.created_at

string<date-time>

required

Timestamp representing the date and time when the redeemable was assigned. The value is shown in the ISO 8601 format.

Example:

"2024-03-22T17:48:25.910Z"

holders.redeemable_id

string

required

Identifier of the redeemable item.

Example:

"v_GXVguPhq2khgFxH7GrRXWA91gDr1LiA1"

holders.redeemable_object

string

required

Type of the redeemable.

Example:

"voucher"

holders.customer_id

string

required

Unique identifier of the customer.

Example:

"cust_p1ufreYbVbwZ1x70nFkH9rF9"

holders.holder_role

enum<string>

required

Role of the holder.

Available options:

OWNER,

REFERRER,

REFEREE

Example:

"OWNER"

holders.campaign_id

string

required

Unique identifier of the campaign as assigned by Voucherify.

Example:

"camp_weer1c3p5ZgktqfW56RfoNaG"

holders.campaign_type

enum<string>

default:REFERRAL_PROGRAM

required

Defines the type of the campaign.

Available options:

REFERRAL_PROGRAM

Example:

"REFERRAL_PROGRAM"

holders.voucher_type

enum<string>

required

Defines the type of the voucher.

Available options:

GIFT_VOUCHER,

DISCOUNT_VOUCHER,

LOYALTY_CARD

Example:

"DISCOUNT_VOUCHER"

holders.object

enum<string>

default:redeemable_holder

required

The type of the object represented by JSON.

Available options:

redeemable_holder

holders.metadata

object

A set of custom key/value pairs that you can attach to a redeemable holder. The metadata object stores all custom attributes assigned to the redeemable_holder object.

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

⌘I

Introduction

Endpoints

Events

Add Referral Code Holders

Authorizations

Path Parameters

Body

Response