> ## Documentation Index
> Fetch the complete documentation index at: https://developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find a contact

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

```http theme={null}
GET /api/v3/contacts/id
```

To this endpoint you can send one (or several) of the following parameters in the query string:

* email
* socialSecurityNumber
* mobilePhone
* customKey

## Request examples

<Warning>
  As can be seen in the examples given below, parameters sent in a query string must always be *URL encoded*.
</Warning>

```http By email theme={null}
GET /api/v3/contacts/id?email=john.doe%40gmail.com
```

```http By socialSecurityNumber theme={null}
GET /api/v3/contacts/id?socialSecurityNumber=196903027573
```

```http By mobilePhone theme={null}
GET /api/v3/contacts/id?mobilePhone=%2B46735654321
```

<Tip>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).</Tip>

```http By customKey theme={null}
GET /api/v3/contacts/id?customKey=999888777
```

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

<Warning>
  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.
</Warning>

A request would look like this:

```http A request using any theme={null}
GET /api/v3/contacts/id?any=john.doe%40gmail.com
```

Or this:

```http Another request using any theme={null}
GET /api/v3/contacts/id?any=999888777
```

<Tip>
  The `contactType` value can also be sent in the query string along with the above parameters but it is not required.
</Tip>

## 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:

```json Multiple matches response theme={null}
{
  "errorCode": "MultipleMatches",
  "messageDetails": {
    "multipleMatchesFound": [
      "1cdd503c-b8cf-1111-a001-b05b00c888a4",
      "2a361f42-f831-2222-852d-b0610100adef"
    ]
  },
  "message": "Exception of type 'Voyado.Api.ApiException' was thrown.",
  "requestId": "f0930fe5-3333-4700-dddd-2ab2653ddf0c"
}
```

<Tip>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.</Tip>