Guest REST API v2 (legacy)

Important

A newer version of this REST API (v2.1) is available. If you're new to this REST API, use the new version. Alternatively, if you're already using the old version, read about the differences between v2 and v2.1 so you can upgrade.

A guest object is the core entity of Sitecore CDP. The personal data of a customer or prospect is recorded and stored, and all relevant transactional and behavioral data is linked in a guest profile.

The following are guest attributes:

Attribute	Type	Description	Example(s)
`firstSeen`	ISO 8601 Date/Time UTC	The first seen date for the guest.	`"2025-01-01T16:17:16.000Z"`
`lastSeen`	ISO 8601 Date/Time UTC	The last time the guest interacted with your brand. If the guest is currently online and is interacting with your brand, this returns the date and timestamp of when the current session started.	`"2025-01-01T16:17:16.000Z"`
`guestType`	string enum (lowercase)	The level of identity obtained.	Must be one of the following: `"visitor"` `"customer"` `"traveller"`
`title`	string (title case)	The title of the guest.	`"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"`
`firstName`	string (title case)	The first name of the guest.	`"John"`
`lastName`	string (recommend title case)	The last name of the guest.	`"Doe"`
`gender`	string (lowercase)	The gender of the guest.	`"male", "female", "unknown"`
`dateOfBirth`	ISO 8601 Date/Time UTC Validation: Date must be in the past.	The date of birth of the guest.	`"1985-12-24T00:00Z"`
`emails`	JSON array of strings	The email addresses of the guest.	`["[email protected]", "[email protected]" ]`
`phoneNumbers`	JSON array of strings	The phone numbers of the guest.	`[ "+353161123345", "+353861123311" ]`
`language`	string (2 letter ISO 639 language code)	The preferred language of the guest.	`"EN", "FR", "DE"`
`nationality`	string (title case)	The nationality of the guest.	`"Irish", "British", "Spanish", "French"`
`passportNumber`	string (uppercase)	The passport number of the guest.	`"PZ4A9565"`
`passportExpiry`	string	The expiry date of the guest's passport.	`"2025-01-01T00:00:00.000Z"`
`street`	JSON array of strings (title case)	The street address of the guest.	`["Ashford House", "Tara Street", "Dublin 2"]`
`city`	string (title case)	The guest's city.	`"Dublin", "London", "Madrid", "Paris"`
`country`	string (2 letter ISO 3166-1 Alpha-2 country code)	The guest's country.	`"IE", "GB", "ES", "FR"`
`postCode`	string (uppercase)	The guest's postcode.	`"D2"`
`state`	string (title case)	The guest's state.	`"Oregon"`
`identifiers`	JSON array of JSON objects	A list of identifiers for the guest.	`[ { "provider":"SITECORE_IDENTITY_SYSTEM", "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41", "expiryDate":"2025-08-23T16:17:16.000Z" } ]`

The following are identifier model attributes:

Attribute	Description	Type	Example(s)	Required/optional
`provider`	The identifier provider.	string	`"ProfileSystem"`	Required
`id`	The identifier ID.	string	`"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41"`	Required
`expiryDate`	The expiry date of the identifier.	ISO 8601 Date/Time UTC	`"2025-01-01T16:17:16.000Z"`	Optional

The following are the standard response attributes:

Attribute	Description	Type	Example(s)
`href`	The resource fully qualified location Uniform Resource Identifier (URI).	string	`"https://{apiEndpoint}/v2/{resourceName}/{resourceRef}"`
`ref`	The reference of the resource.	string UUID	`"9d94ee11-7043-4b71-980c-a777d00a7b46"`
`createdAt`	Date and time when the resource was created in Sitecore CDP.	ISO 8601 Date/Time UTC	`"2025-01-01T16:17:16.000Z"`
`modifiedAt`	Date and time when the resource was updated in Sitecore CDP.	ISO 8601 Date/Time UTC	`"2025-01-01T16:17:16.000Z"`

Do you have some feedback for us?

If you have suggestions for improving this article,