Referral Event Input

Input representation of the request to create a referral event.

JSON Examples 

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   }

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}

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}

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}

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}

Properties 

activityDateTime 

Type: String

Description: The date and time when the referral event took place.

Required or Optional: Optional. This field is required only if the joining date isn’t specified in the request.

Available Version: 59.0

contactId 

Type: String

Description: Contact ID of the referred friend.

Required or Optional: Optional. Required if the referral record exists.

Available Version: 59.0

email 

Type: String

Description: Email address of the referred friend.

Required or Optional: Optional. Required only if the contact ID of the referred friend doesn’t exist.

Available Version: 59.0

eventType 

Type: String

Description: Type of event completed by the referred friend or advocate. Possible values are:

  • Enrollment
  • Purchase
  • Refer

Required or Optional: Required

Available Version: 59.0

firstName 

Type: String

Description: First name of the referred friend.

Required or Optional: Optional. Required only if the contact ID of the referred friend doesn’t exist.

Available Version: 59.0

joiningDate 

Type: String

Description: 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.

Required or Optional: Optional. This field is required only if the activity date and time isn’t specified in the request.

Available Version: 59.0

lastName 

Type: String

Description: Family name of the referred friend.

Required or Optional: Optional. Required only if the contact ID of the referred friend doesn’t exist.

Available Version: 59.0

mobilePhone 

Type: String

Description: Mobile phone of the referral.

Required or Optional: Optional

Available Version: 68.0

optInWhatsApp 

Type: Boolean

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

Required or Optional: Optional

Available Version: 62.0

orderReferenceId 

Type: String

Description: External purchase order ID.

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

Required or Optional: Optional

Available Version: 59.0

productId 

Type: String

Description: ID of the product purchased by the referral.

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

Required or Optional: Optional

Available Version: 59.0

purchaseAmount 

Type: Double

Description: Price of the product purchased by the referred friend.

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

Required or Optional: Optional

Available Version: 59.0

purchaseQuantity 

Type: Integer

Description: Quantity purchased by the referred friend.

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

Required or Optional: Optional

Available Version: 59.0

referralAdditionalAttributes 

Type: Map<String, String>

Description: Key value pairs for additional information about the referred friend.

Required or Optional: Optional

Available Version: 59.0

referralChannel 

Type: String

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

Required or Optional: Optional

Available Version: 62.0

referralCode 

Type: String

Description: 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.

Required or Optional: Required

Available Version: 59.0

referralEmails 

Type: String[]

Description: The email addresses of the referral friends.

Required or Optional: Optional

Available Version: 59.0

referralMobilePhones 

Type: String[]

Description: The mobile phone numbers of the referral friends.

Required or Optional: Optional

Available Version: 68.0

referralStage 

Type: String

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

Required or Optional: Optional

Available Version: 62.0

referredPartyJournalSubtype 

Type: String

Description: The activity for which the referred members are rewarded.

Required or Optional: Optional

Available Version: 62.0

transactionJournalAdditionalAttributes 

Type: Map<String, String>

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

Required or Optional: Optional

Available Version: 59.0

contactLocale 

Type: String

Description: Locale for contact for WhatsApp distribution channel.

Required or Optional: Optional

Available Version: 62.0

contactFieldForLocale 

Type: String

Description: Contact field used for Locale WhatsApp distribution channel.

Required or Optional: Optional

Available Version: 62.0