Skip to main content

Find contact

Use this endpoint to check if a certain contact exists in Engage:


To this you can send one (or several) of the following parameters:


GET /api/v2/contacts/id?


GET /api/v2/contacts/id?mobilePhone=%2B46735654321


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) which is the identification number given in Sweden before a person has their personal identity number.

GET /api/v2/contacts/id?socialSecurityNumber=196903027573


As the customKey value you can send either a contact's memberNumber or externalId, depending on how your tenant is set up. Your Voyado Engage team can help you here.

GET /api/v2/contacts/id?customKey=999888777


The "any" parameter will, as the name suggests, accept any of the above values. They are scanned in the following order: email, socialSecurityNumber, mobilePhone and then customKey.

For example:

GET /api/v2/contacts/id?

GET /api/v2/contacts/id?any=999888777


The contactType can also be sent in the query string along with the above parameters but it is not required.


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 given the same email, they will all be returned in that response. That will look like this:

  "errorCode": "MultipleMatches",
  "messageDetails": {
    "multipleMatchesFound": [
  "message": "Exception of type 'Voyado.Api.ApiException' was thrown.",
  "requestId": "f0930fe5-3333-4700-dddd-2ab2653ddf0c"

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.


As can be seen in all of the examples above, the parameters sent in a query string must always be URL encoded.