Skip to main content

Identifying a contact

This is how an Engage customer is identified through Cow Hills.

Check if a contact exists

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:

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:


You must use version 1 of the /contacts endpoint in the Engage API to check if a contact exists. Contact type is not needed.

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.

A) The contact is already in the system

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

  "totalResults": 1,
  "results": [
      "firstName": "Example",
      "lastName": "Examplesson",
      "email": "",
      "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.

B) If the contact can't be found in the system

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

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

Displaying the contact's data in the POS

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.


Extra attributes are read-only in the POS and can't be changed from there.