Identification by discoveryKey

Engage and Elevate both identify the contact/customer by a unique alphanumeric identifier, a GUID/UUID(4), that looks something like this: 5c9b35d6-28d8-4520-8900-a89600f7f0c5.

There are two attributes and one ID to consider when linking a contact across the two products:

The e-com generates and sends a customerKey to Elevate (see the Elevate docs for details regarding the customerKey)
The e-com sends the same ID as discoveryKey to Engage

Before the discoveryKey can be included in calls to Engage, your Voyado Engage specialist needs to activate this in your tenant, then:

Save the Elevate customerKey in the field discoveryKey in Engage. The discoveryKey in Engage is then the customerKey in Elevate.
Always include the discoveryKey when a contact is updated or created in Engage.
Do this whether you are using the API or a file import.
The contactId in Engage and customerKey in Elevate are automatically connected through the discoveryKey.

Setting or updating a contact's discoveryKey

Important

For in-depth information about the Voyado API refer to the API documentation and your OpenAPI (Swagger) page.

You should always provide the discoveryKey value during the creation of a new contact in Engage. When updating an existing contact, there is no need to send discoveryKey unless it has changed. See the documentation on the /contacts endpoint for more details.

To update the discoveryKey, a call like this is made:

POST /api/v2/contacts/{contactId}

With a payload of this form:

{
  "discoveryKey": "64fe7cb7-4792-44f6-900e-c9dc8e27aaaa"
}

The response to a successful update will contain the contact data, including the newly updated discoveryKey listed under attributes:

{
  "id": "aac97fa0-23e7-1111-ba7e-af1200ecede0",
  "attributes": {
	"firstName": "Example",
	"discoveryKey": "64fe7cb7-4792-44f6-900e-c9dc8e27aaaa",
	…
}

Retrieving a contact's discoveryKey

To fetch a contact's discoveryKey, the /contacts endpoint is also used:

GET /api/v2/contacts/{contactId}

If the specified contact exists, the response will contain the discoveryKey attribute. All contact data will be returned.

{
  "id": "aac97fa0-23e7-1111-ba7e-af1200ecede0",
  "attributes": {
	"firstName": "Example",
	"discoveryKey": "64fe7cb7-4792-44f6-900e-c9dc8e27aaaa",
	…
}

Even if the value of the contactId attribute in Engage is the exact same as the customerKey value in Elevate (a one-to-one equivalence) it is still important to set the discoveryKey attribute in Engage to the same value as the customerKey in Elevate.

DiscoveryKey in soft ID

The Elevate identification can be improved if the discoveryKey contact attribute is included in the Engage soft identification data. If shared in the encrypted URL, all email traffic will be identified on both products. Read more here.

Deprecated

A previously used workaround for integrating Elevate with Engage was the use of a custom contact attribute for Engage contacts, usually referred to as the “apptusId”, to store the Elevate customerKey. This method should be seen as deprecated.

In this section: