Skip to main content
Use this endpoint to check if a certain contact exists in Engage:
To this endpoint you can send one (or several) of the following parameters in the query string:
  • email
  • socialSecurityNumber
  • mobilePhone
  • customKey

​
Request examples

As can be seen in the examples given below, parameters sent in a query string must always be URL encoded.
By email
By socialSecurityNumber
By mobilePhone
Although it’s called “socialSecurityNumber” (sometimes SSN) in Engage, what’s actually used here is a Swedish personal identity number, a Finnish personal identity code or a Swedish coordination numbers (samordningsnummer).
By customKey
As the “customKey” value you can send either a contact’s memberNumber or externalId, depending on how your tenant is set up. Your Voyado team can help you here.

​
The any parameter

The “any” parameter accepts any of the above values. To find a match, they are scanned using the value in the “any” parameter in this order:
  • email
  • socialSecurityNumber
  • mobilePhone
  • customKey
The scanning of attributes will halt as soon as the given value passes validation for an attribute, even if that value returns no matches. So if a customKey is used with values that could validate as another attribute, for example as mobileNumber, then the scanning will stop with a 404 ContactNotFound response and no match will be returned.
A request would look like this:
A request using any
Or this:
Another request using any
The contactType value can also be sent in the query string along with the above parameters but it is not required.

​
Responses

If the request has been successful, meaning the contact exists, you’ll get a HTTP 200 OK response along with the contactId which is the unique identifier for your contact and looks something like this: 2e40b702-2767-4abe-ae99-aa510108e22b. This contactId is what you will then use to fetch the contact’s data. If the request has not been successful, you’ll get one of the following HTTP error codes:
  • 400: InvalidEmailAddress, InvalidPhoneNumber, InvalidSocialSecurityNumber, InvalidContactType, InvalidSearchQuery
  • 404: ContactNotFound
  • 409: MultipleMatches
  • 500: InvalidSystemConfiguration
Response codes could change, so always check your Swagger page to see the latest ones.

​
Multiple responses

It can happen that a search returns more than one contactId. For example, if you do a search with the email parameter and several contacts have supplied the same email, they will all be returned in that response. That will look like this:
Multiple matches response
For multiple matches, contact IDs are returned sorted by CreationTime and in ascending order. This means in the order in which they were created, with the earliest created coming first.