---
title: "Add Referral Code Holders"
method: POST
path: "/v1/referrals/members/{memberId}/holders"
tags: ["Referrals"]
---

# Add Referral Code Holders

`POST /v1/referrals/members/{memberId}/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](/api-reference/publications/create-publication) endpoint.

> 📘 Alternative endpoint
>
>This endpoint is an alternative to the [Add Referral Code Holders endpoint](/api-reference/referrals/add-referral-code-holders-with-campaign-id). The URL was re-designed to retrieve the referral member holders without providing the `campaignId` as a path paremeter.

## Request body

- ReferralsMembersHoldersCreateInBulkRequestBody — Request body schema for **POST** `v1/referrals/{campaignId}/members/{memberId}/holders` and **POST** `v1/referrals/members/{memberId}/holders`.
  - `holders` Customer[], 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.
    - `id` string — The ID of an existing customer.
    - `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.
    - `name` string — Customer's first and last name.
    - `description` string — An arbitrary string that you can attach to a customer object.
    - `email` string — Customer's email address.
    - `phone` string — Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.
    - `birthday` string, date — `Deprecated`. ~~Customer's birthdate; format YYYY-MM-DD~~.
    - `birthdate` string, date — Customer's birthdate; format YYYY-MM-DD.
    - `address` object, nullable — Customer's address.
      - `city` string — City
      - `state` string — State
      - `line_1` string — First line of address.
      - `line_2` string — Second line of address.
      - `country` string — Country.
      - `postal_code` string — Postal code.
    - `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 `200`

Returns a list of redeemable holder objects.

- ReferralsMembersHoldersCreateInBulkResponseBody — Response body schema for **POST** `v1/referrals/{campaignId}/members/{memberId}/holders` and **POST** `v1/referrals/members/{memberId}/holders`.
  - `holders` RedeemableHolder[], required — Contains an array of referral card holders who are the customers sent in the request.
    - `id` string, required — Unique identifier of the redeemable holder.
    - `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.
    - `redeemable_id` string, required — Identifier of the redeemable item.
    - `redeemable_object` string, required — Type of the redeemable.
    - `customer_id` string, required — Unique identifier of the customer.
    - `holder_role` 'OWNER' | 'REFERRER' | 'REFEREE', required — Role of the holder.
    - `campaign_id` string, required — Unique identifier of the campaign as assigned by Voucherify.
    - `campaign_type` 'REFERRAL_PROGRAM', required — Defines the type of the campaign.
    - `voucher_type` 'GIFT_VOUCHER' | 'DISCOUNT_VOUCHER' | 'LOYALTY_CARD', required — Defines the type of the voucher.
    - `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.
    - `object` 'redeemable_holder', required — The type of the object represented by JSON.

## Other responses

- `400` — Returns an error if the payload is incorrect or the referral card has not been published yet.
- `403` — Returns an error if the user is missing permissions.
- `404` — Returns an error indicating that the referral code with a given ID was not found.
- `409` — Returns an error if a voucher code already exists, the customer has been already assigned as a referrer or referee, or the `source_id` and `id` of the same customer has been used in two different objects in the request.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/versions/4982266e0494/schema)