Identifying a contact

Cow Hills uses v1 of the Engage API endpoint /contacts. Version 1 is used because searching based on address and postal (zip) code is something still commonly done in retailers in the Netherlands. Version 1 of the Engage API supports this.

This is an example swagger page for the Engage API:

https://voyadodemoecom.voyado.com/api/v2/ui/index

Select "Voyado API v1" in the top-right dropdown to access the version 1 API.

Now select "contacts" and the first option "Get contacts through query". Create your search query with the details you will use, and send it as the query parameter.

For example, your query might be: ZipCode:"111 11" AND Street:"Examplegatan 5"

The full API call is then:

https://voyadodemoecom.voyado.com/api/v1/contacts?query=ZipCode%3A%22111%2011%22%20AND%20Street%3A%22Examplegatan%205%22

Note that /contacts is the only v1 endpoint used. Everything else in this integration uses the Engage v2 API.

Two things can happen next: either this contact is already in the system, or they are not.

In this case, data in this format will be returned:

{
  "totalResults": 1,
  "results": [
    {
      "firstName": "Example",
      "lastName": "Examplesson",
      "email": "example@example.com",
      "socialSecurityNumber": null,
      "mobilePhone": null,
      "zipCode": "111 11",
      "street": "Examplegatan",
      "city": null,
      "externalId": "11de71a1-4bc6-4a11-a4ef-8ebac0480b11",
      "id": "d0011111-45f2-492f-8d31-aec500a07f11",
      "contactType": "Member",
      "memberNumber": "01010101010101"
    }
  ]
}

The value id is the unique contact id and will be used in the display step below.

In this case, Cow Hills will create a new contact in Engage as contact type Member. See the Engage Contacts documentation for details.

This creates a contact and returns a data set containing id, their unique contact ID value.

Now that the contact has been identified, Cow Hills takes their unique id and makes a lookup against the /contactoverview endpoint in version 2 of the API.

You can read more about that endpoint here.

Cow Hills now fetches the contact's full data from Engage, containing such information as address, target audience, promotions, tier levels, purchase history, points and consents. This is used to populate the POS, depending on what the retailer wants to see.

Cow Hills can also fetch extra contact attributes from Engage. These are configured under "sections" in Cow Hills.