Referral Event (POST)

Create referral event records when an advocate refers a friend, or when referred friends sign up or make a purchase.

Special Access Rules 

To use this resource, your org must have person accounts enabled.

Resource 

1/referral-program/referral-event

Resource Example:

1https://yourInstance.salesforce.com/services/data/v68.0/referral-program/referral-event

Available Version 

59.0

Requires Chatter 

No

HTTP Methods 

POST

Request Body for POST 

JSON Example 

Here’s an example of a payload for an event where the existing member refers his friend, Michael Clare.

1{
2   "referralCode":"2G11QW4G-PROMOCODE2809",
3   "firstName":"Michael",
4   "lastName":"Clare",
5   "email":"mclare@salesforce.com",
6   "activityDateTime":"2023-09-13T00:00:00",
7   "eventType":"Refer",
8   "referredPartyJournalSubtype":"Sample Activity",
9   "referralAdditionalAttributes":{
10      "attributes":{
11         "phoneNumber":"1234567890",
12         "emailOptOut":true
13      }
14   }

JSON Example 

Here’s an example of a payload to know which channel did the referral come from.

1{
2 "referralCode":"2G11QW4G-PROMOCODE2809",
3 "contactId": "003xx000004WkhEAAS",
4 "firstName":"Michael",
5 "lastName":"Clare",
6 "email":"michael.clare@salesforce.com",
7 "joiningDate":"2021-04-13T00:00:00",
8 "eventType": "Purchase",
9 "referralChannel":"Facebook",
10 "purchaseAmount": 40000,
11 "purchaseQuantity": 34,
12 "referralAdditionalAttributes" : {
13 "attributes": {
14 "phoneNumber":"1234567890",
15 "PersonHasOptedOutOfEmail": false,
16 }
17 },
18 "transactionJournalAdditionalAttributes": {
19 },
20 "orderReferenceId": "003xx00000000fxEAA"
21}

JSON Example 

Here’s an example of a payload for an event where Michael Clare signs up for the referral program.

1{
2   "referralCode":"2G11QW4G-PROMOCODE2809",
3   "contactId":"003xx000004WkhEAAS",
4   "activityDateTime":"2023-09-13T00:00:00",
5   "eventType":"Enrollment"
6}

JSON Example 

Here’s an example of a payload for an event where Michael Clare purchases a product.

1{
2   "referralCode":"2G11QW4G-PROMOCODE2809",
3   "contactId":"003xx000004WkhEAAS",
4   "activityDateTime":"2023-09-13T00:00:00",
5   "referralStage":"Purchase",
6   "productId":"01txx0000006iGyAAI",
7   "purchaseAmount":40000,
8   "purchaseQuantity":34,
9   "referralAdditionalAttributes":{
10      "attributes":{
11         "phoneNumber":"1234567890",
12         "emailOptOut":true
13      }
14   },
15   "transactionJournalAdditionalAttributes":{
16      
17   }
18}

JSON Example 

Here’s an example of a payload for an event where the existing member refers multiple friends.

1{
2   "referralCode":"0UGUXMNA-promotiontest098",
3   "referralEmails":{
4      "emails":[
5         "kit.ryan@salesforce.com",
6         "amy.sh@salesforce.com"
7      ]
8   },
9   "activityDateTime":"2024-02-12T00:00:00",
10   "eventType":"Refer",
11   "referralAdditionalAttributes":{
12      "attributes":{
13         
14      }
15   },
16   "transactionJournalAdditionalAttributes":{
17      
18   }
19}

Request Body Properties 

activityDateTime 

The date and time when the referral event took place.

Type: String. Optional. This field is required only if the joining date isn’t specified in the request. Available in version 59.0.

contactId 

Contact ID of the referred friend.

Type: String. Optional. Required if the referral record exists. Available in version 59.0.

email 

Email address of the referred friend.

Type: String. Optional. Required only if the contact ID of the referred friend doesn’t exist. Available in version 59.0.

eventType 

Type of event completed by the referred friend or advocate.

Possible values are:

  • Enrollment
  • Purchase
  • Refer

Type: String. Required. Available in version 59.0.

firstName 

First name of the referred friend.

Type: String. Optional. Required only if the contact ID of the referred friend doesn’t exist. Available in version 59.0.

joiningDate 

Date the referred friend joined as a new customer.

This field has been deprecated. In API version 59.0 and later, use the new activityDateTime field.

Type: String. Optional. This field is required only if the activity date and time isn’t specified in the request. Available in version 59.0.

lastName 

Family name of the referred friend.

Type: String. Optional. Required only if the contact ID of the referred friend doesn’t exist. Available in version 59.0.

mobilePhone 

Mobile phone of the referral.

Type: String. Optional. Available in version 68.0.

optInWhatsApp 

Indicates whether the new customer has opted in to receive WhatsApp messages from the company.

Type: Boolean. Optional. Available in version 62.0.

orderReferenceId 

External purchase order ID.

This field is applicable only when the event type is Purchase.

Type: String. Optional. Available in version 59.0.

productId 

ID of the product purchased by the referral.

This field is applicable only when the event type is Purchase.

Type: String. Optional. Available in version 59.0.

purchaseAmount 

Price of the product purchased by the referred friend.

This field is applicable only when the event type is Purchase.

Type: Double. Optional. Available in version 59.0.

purchaseQuantity 

Quantity purchased by the referred friend.

This field is applicable only when the event type is Purchase.

Type: Integer. Optional. Available in version 59.0.

referralAdditionalAttributes 

Key value pairs for additional information about the referred friend.

Type: Map<String, String>. Optional. Available in version 59.0.

referralChannel 

Channels such as email and social media that are used to refer a friend.

Type: String. Optional. Available in version 62.0.

referralCode 

Referral code used by the referred friend to sign up or make a purchase. It’s a combination of the referral code and promotion code in the format, referralCode-promotionCode.

Type: String. Required. Available in version 59.0.

referralEmails 

The email addresses of the referral friends.

Type: String[]. Optional. Available in version 59.0.

referralMobilePhones 

The mobile phone numbers of the referral friends.

Type: String[]. Optional. Available in version 68.0.

referralStage 

The event type to consider based on the stage of the referral promotion.

Type: String. Optional. Available in version 62.0.

referredPartyJournalSubtype 

The activity for which the referred members are rewarded.

Type: String. Optional. Available in version 62.0.

transactionJournalAdditionalAttributes 

Additional details of the transaction journal that is created for the event.

Type: Map<String, String>. Optional. Available in version 59.0.

contactLocale 

Locale for contact for WhatsApp distribution channel.

Type: String. Optional. Available in version 62.0.

contactFieldForLocale 

Contact field used for Locale WhatsApp distribution channel.

Type: String. Optional. Available in version 62.0.

Response Body for POST 

Referral Event