Referral Event Input | Referral Marketing Developer Guide

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}

Name	Type	Description	Required or Optional	Available Version
`activityDateTime`	String	The date and time when the referral event took place.	Optional This field is required only if the joining date isn’t specified in the request.	59.0
`contactId`	String	Contact ID of the referred friend.	Optional Required if the referral record exists.	59.0
`email`	String	Email address of the referred friend.	Optional Required only if the contact ID of the referred friend doesn’t exist.	59.0
`eventType`	String	Type of event completed by the referred friend or advocate. Possible values are: `Enrollment` `Purchase` `Refer`	Required	59.0
`firstName`	String	First name of the referred friend.	Optional Required only if the contact ID of the referred friend doesn’t exist.	59.0
`joiningDate`	String	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.	Optional This field is required only if the activity date and time isn’t specified in the request.	59.0
`lastName`	String	Family name of the referred friend.	Optional Required only if the contact ID of the referred friend doesn’t exist.	59.0
`orderReferenceId`	String	External purchase order ID. This field is applicable only when the event type is `Purchase`.	Optional	59.0
`productId`	String	ID of the product purchased by the referral. This field is applicable only when the event type is `Purchase`.	Optional	59.0
`purchaseAmount`	Double	Price of the product purchased by the referred friend. This field is applicable only when the event type is `Purchase`.	Optional	59.0
`purchaseQuantity`	Integer	Quantity purchased by the referred friend. This field is applicable only when the event type is `Purchase`.	Optional	59.0
`referralAdditionalAttributes`	Map<String, String>	Key value pairs for additional information about the referred friend.	Optional	59.0
`referralCode`	String	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	59.0
`referralEmails`	String[]	The email addresses of the referral friends.	Optional	59.0
`transactionJournalAdditionalAttributes`	Map<String, String>	Additional details of the transaction journal that is created for the event.	Optional	59.0
referralChannel	String	Channels such as email and social media that are used to refer a friend.	Optional	62.0
referralStage	String	The event type to consider based on the stage of the referral promotion.	Optional	62.0
referredPartyJournalSubtype	String	The activity for which the referred members are rewarded.	Optional	62.0