Sending events

ADD_CONTACTS event

If your organization sends orders using multiple events, the ADD_CONTACTS event is required to identify the guest.

If your organization sends orders using a single event, you do not use the ADD_CONTACTS event.

To send an ADD_CONTACTS event, use the following required attributes:

Attribute	Type	Description	Example
`channel`	string (uppercase)	The touchpoint where the user interacts with your brand.	`"MOBILE_APP"` `"MOBILE_WEB"` `"WEB"`
`type`	string (uppercase)	The type of the event that takes place when the user interacts with your brand.	`"ADD_CONTACTS"`
`language`	string (uppercase ISO 639-1)	The language the user is using your app in.	`"DE"` `"EN"` `"FR"`
`currency`	string (uppercase ISO 4217)	The alphabetic currency code of the currency the user is using in your app.	`"EUR"` `"GBP"` `"USD"`
`page`	string	The name of the webpage where the interaction with your brand takes place. This is a custom value of your choice.	`"home"` `"contact-us.html"`
`pos`	string	The name of the point of sale where the interaction with your brand takes place.	`"myretailsite/ireland"` `"spinair.com/france"`
`browser_id`	string	The browser ID.	`"a38b230c-11eb-4cf9-8d5d-274e9f344925"`
`contact`	array of objects	Contact details.	N/A

The contact array of objects:

Attribute	Type	Description	Example	Required/optional
`title`	string (title case)	The title of the contact.	`"Br", "Brigadier", "Capt", "Colonel", "Dame", "Dr", "Elder", "Fr", "General", "Hon", "Judge", "Lord", "Master", "Miss", "Mr", "Mrs", "Ms", "Mstr", "Prof", "Rabbi", "Rev", "Shaikha", "Sheikh", "Sir", "Sister", "Sr"`	Optional
`firstname`	string (title case recommended)	The first name of the contact.	`"Jane"`	Optional
`lastname`	string (title case recommended)	The last name of the contact.	`"Doe"`	Optional
`mobile`	string	The mobile number of the contact.	`"+3531234567"`	Optional
`phone`	string	The phone number of the contact.	`"+3531234567"`	Optional
`street`	array of strings (title case recommended)	The street address of the contact.	`["Tara Street"]`	Optional
`city`	string (title case recommended)	The city address of the contact.	`"Dublin"`	Optional
`state`	string (title case recommended)	The state address of the contact.	`"Oregon"`	Optional
`country_code`	string (uppercase ISO 3166-1 alpha-2)	The country code of the contact.	`"IE"`	Optional
`postal_code`	string (uppercase recommended)	The postcode of the contact.	`"D15"`	Optional
`dob`	string (ISO 8601)	The date of birth of the contact.	`"1990-08-23T00:00"`	Optional
`email`	string (lowercase recommended)	The email address of the contact.	`"[email protected]"`	Optional
`gender`	string (lowercase)	The gender of the contact.	`"male"` `"female"` `"rather_not_say"`	Optional
`identifiers`	array of objects	The identifiers that are used to identify the users of your app.	N/A	Required

The contact.identifiers array of objects:

Attribute	Type	Description	Example	Required/optional
`id`	string	The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.	`"123456"`	Required
`provider`	string	The name of your organization's identity system, external to Sitecore Personalize, that provided the unique guest identifier.	`"BXLP"`	Required
`expiryDate`	string (ISO 8601)	The date the unique guest identifier expires. This is determined by your organization's identity system.	`"2026-04-15T08:`39 `.868Z"`	Optional

Example 48. ADD_CONTACTS event object

{
   "channel": "MOBILE_APP",
   "type": "ADD_CONTACTS",
   "language": "EN",
   "currency": "EUR",
   "page": "home page",
   "pos": "myretailsite/ireland",
   "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925",
   "contact": [
      {
         "title": "Mr",
         "firstname": "Jack",
         "lastname": "Smith",
         "mobile": "(+353)1234567",
         "phone": "(+353)1234568",
         "street": [
            "123 Fake Street"
         ],
         "city": "Dublin",
         "country_code": "IE",
         "postal_code": "1234",
         "dob": "1975-04-23T00:00",
         "email": "[email protected]",
         "gender": "male",
         "identifiers": [
            {
               "provider": "BXLP",
               "id": "123456",
               "expiryDate": "2026-01-01T16:`17:16`.000Z",
            }
         ]
      }
   ]
}

The ADD_CONTACTS event is required to create an order in Sitecore CDP. The contact is the owner of the order, meaning orders cannot exist in Sitecore CDP without a contact. The contact on the order must be a customer guest_type.

To send an ADD_CONTACTS event, use the following required attributes:

Attribute	Type	Description	Example
`channel`	string (uppercase)	The touchpoint where the user interacts with your brand.	`"MOBILE_APP"` `"MOBILE_WEB"` `"WEB"`
`type`	string (uppercase)	The type of the event that takes place when the user interacts with your brand.	`"ADD_CONTACTS"`
`language`	string (uppercase ISO 639-1)	The language the user is using your app in.	`"DE"` `"EN"` `"FR"`
`currency`	string (uppercase ISO 4217)	The alphabetic currency code of the currency the user is using in your app.	`"EUR"` `"GBP"` `"USD"`
`page`	string	The name of the webpage where the interaction with your brand takes place. This is a custom value of your choice.	`"home"` `"contact-us.html"`
`pos`	string	The name of the point of sale where the interaction with your brand takes place.	`"myretailsite/ireland"` `"spinair.com/france"`
`browser_id`	string	The browser ID.	`"a38b230c-11eb-4cf9-8d5d-274e9f344925"`
`contact`	array of objects	Contact details.	N/A

The contact array of objects:

Attribute	Type	Description	Example	Required/optional
`title`	string (title case)	The title of the contact.	`"Br", "Brigadier", "Capt", "Colonel", "Dame", "Dr", "Elder", "Fr", "General", "Hon", "Judge", "Lord", "Master", "Miss", "Mr", "Mrs", "Ms", "Mstr", "Prof", "Rabbi", "Rev", "Shaikha", "Sheikh", "Sir", "Sister", "Sr"`	Required
`firstname`	string (title case recommended)	The first name of the contact.	`"Jane"`	Required
`lastname`	string (title case recommended)	The last name of the contact.	`"Doe"`	Required
`mobile`	string	The mobile number of the contact.	`"+3531234567"`	Optional
`phone`	string	The phone number of the contact.	`"+3531234567"`	Optional
`street`	array of strings (title case recommended)	The street address of the contact.	`["Tara Street"]`	Optional
`city`	string (title case recommended)	The city address of the contact.	`"Dublin"`	Optional
`state`	string (title case recommended)	The state address of the contact.	`"Oregon"`	Optional
`country_code`	string (uppercase ISO 3166-1 alpha-2)	The country code of the contact.	`"IE"`	Optional
`postal_code`	string (uppercase recommended)	The postcode of the contact.	`"D15"`	Optional
`dob`	string (ISO 8601)	The date of birth of the contact.	`"1990-08-23T00:00"`	Optional
`email`	string (lowercase recommended)	The email address of the contact.	`"[email protected]"`	Required: If your organisation uses the email attribute to determine guest identity. Optional: If your organisation uses identifier(s) to determine guest identity.
`gender`	string (lowercase)	The gender of the contact.	`"male"` `"female"` `"rather_not_say"`	Optional
`identifiers`	array of objects	The identifiers that are used to identify the users of your app.	N/A	Required: If your organisation uses identifier(s) to determine guest identity. Optional: If your organisation uses the email attribute to determine Guest identity.

The contact.identifiers array of objects:

Attribute	Type	Description	Example	Required/optional
`id`	string	The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.	`"123456"`	Required
`provider`	string	The name of your organization's identity system, external to Sitecore Personalize, that provided the unique guest identifier.	`"BXLP"`	Required
`expiryDate`	string (ISO 8601)	The date the unique guest identifier expires. This is determined by your organization's identity system.	`"2026-04-15T08:`39 `.868Z"`	Optional

Notice

You do not have to include both the contact.identifiers array and contact.email attribute when sending an ADD_CONTACTS event. Your organization either uses the contact.identifiers array or the contact.email attribute to determine the identity of the guest. If your organization uses the contact.email attribute to determine the guest's identity, then the contact.identifiers array is ignored. If your organization uses the contact.identifiers array to determine the guest's identity, then sending the contact.email attribute is optional.

Example 49. ADD_CONTACTS event object

{
   "channel": "MOBILE_APP",
   "type": "ADD_CONTACTS",
   "language": "EN",
   "currency": "EUR",
   "page": "home page",
   "pos": "myretailsite/ireland",
   "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925",
   "contact": [
      {
         "title": "Mr",
         "firstname": "Jack",
         "lastname": "Smith",
         "mobile": "(+353)1234567",
         "phone": "(+353)1234568",
         "street": [
            "123 Fake Street"
         ],
         "city": "Dublin",
         "country_code": "IE",
         "postal_code": "1234",
         "dob": "1975-04-23T00:00",
         "email": "[email protected]",
         "gender": "male",
         "identifiers": [
            {
               "provider": "BXLP",
               "id": "123456",
               "expiryDate": "2026-01-01T16:`17:16`.000Z",
            }
         ]
      }
   ]
}

If you have suggestions for improving this article, let us know!