# Search contact by Email, Mobile, Name

### Overview

Any active contact within an Airship account can searched for, and returned via the REST API.

This allows third parties to identify contact details based on a key identifier, if multiple contacts exist against a query (i.e. Name = John Smith), then an array of contacts will be returned in the response. 

All queries by Email or Mobile will only return a single result, as they are unique in an account.

### Example Request

{% tabs %}
{% tab title="GET" %}

```
https://api.airship.co.uk/v1/contacts
```

{% endtab %}
{% endtabs %}

### Configuration

#### Headers

| Field                           | Notes                                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Authentication` (bearer token) | The authentication token is linked to the account that you are searching bookings in. If you are unsure of what your Authentication token is, ask our support team to confirm. |

#### Body

| Field                           | Notes                                                                                                                                                    |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_id`                    | The account ID represents the account that you are searching bookings in. If you are unsure of what your account ID is, ask our support team to confirm. |
| `email`                         | Email address of contact you are searching for                                                                                                           |
| `mobile_number`                 | Mobile number of contact you are searching for                                                                                                           |
| `name (first_name / last_name)` | First / last name of contact you are searching for                                                                                                       |

### **Basic payload example**

#### Email search

Contacts can be searched for by email address, there is some basic regex validation on the email to ensure it is in a valid format.

{% tabs %}
{% tab title="Request" %}

```json
{
    "account_id": 3,
    "email": "john.smith@airship.co.uk"
}
```

{% endtab %}

{% tab title="200 Response" %}

```json
{
    "allow_sms": false,
    "allow_email": true,
    "allow_call": false,
    "allow_snail_mail": false,
    "udfs": [],
    "units": [
        {
            "id": 14458,
            "name": "Head Office",
            "groups": [
                {
                    "id": 126832,
                    "name": "Football visitor"
                },
                {
                    "id": 126842,
                    "name": "Christmas Competition entry"
                }
            ]
        },
        {
            "id": 14478,
            "name": "London venue",
            "groups": [
                {
                    "id": 126778,
                    "name": "WIFI"
                }
            ]
        }
    ],
    "feedback": "https://api.airship.co.uk/v1/contact/51616336/feedback",
    "bookings": "https://api.airship.co.uk/v1/contact/51616336/bookings",
    "purchases": "https://api.airship.co.uk/v1/contact/51616336/purchases",
    "proof_of_presence": "https://api.airship.co.uk/v1/contact/51616336/pops",
    "id": 51616336,
    "gender": "M",
    "title": "Mr",
    "first_name": "John",
    "last_name": "Smith",
    "dob": "1984-11-27",
    "building_name": "",
    "building_num_street": "2 Test Way",
    "locality": "",
    "postcode": "L1 1AA",
    "city": "London",
    "country": "United Kingdom",
    "county": "",
    "mobile_number": "447816000001",
    "home_number": "",
    "preferred_method_id": "0",
    "work_number": "",
    "email": "John.Smith@airship.co.uk",
    "source_id": "134747",
    "membership_number": "",
    "membership_type": ""
}
```

{% endtab %}

{% tab title="422 Response" %}
A 422 response can be given in the following scenarios;

1. Account ID is incorrect

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "account_id": [
            "You do not have access to this account"
        ]
    }
}
```

2\. Invalid email address

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "test.test@airship is not a valid email address"
        ]
    }
}
```

{% endtab %}
{% endtabs %}

#### Mobile search

Contacts can be searched for by Mobile number. All mobile numbers are stored in Airship with the country code (447....), and the API will automatically add this when you pass in a value.

{% tabs %}
{% tab title="Request" %}

```json
{
    "account_id": 3,
    "mobile_number": "447810000001"
}
```

{% endtab %}

{% tab title="200 Response" %}

```json
{
    "allow_sms": false,
    "allow_email": true,
    "allow_call": false,
    "allow_snail_mail": false,
    "udfs": [],
    "units": [
        {
            "id": 14458,
            "name": "Head Office",
            "groups": [
                {
                    "id": 126832,
                    "name": "Football visitor"
                },
                {
                    "id": 126842,
                    "name": "Christmas Competition entry"
                }
            ]
        },
        {
            "id": 14478,
            "name": "London venue",
            "groups": [
                {
                    "id": 126778,
                    "name": "WIFI"
                }
            ]
        }
    ],
    "feedback": "https://api.airship.co.uk/v1/contact/51616336/feedback",
    "bookings": "https://api.airship.co.uk/v1/contact/51616336/bookings",
    "purchases": "https://api.airship.co.uk/v1/contact/51616336/purchases",
    "proof_of_presence": "https://api.airship.co.uk/v1/contact/51616336/pops",
    "id": 51616336,
    "gender": "M",
    "title": "Mr",
    "first_name": "John",
    "last_name": "Smith",
    "dob": "1984-11-27",
    "building_name": "",
    "building_num_street": "2 Test Way",
    "locality": "",
    "postcode": "L1 1AA",
    "city": "London",
    "country": "United Kingdom",
    "county": "",
    "mobile_number": "447816000001",
    "home_number": "",
    "preferred_method_id": "0",
    "work_number": "",
    "email": "John.Smith@airship.co.uk",
    "source_id": "134747",
    "membership_number": "",
    "membership_type": ""
}
```

{% endtab %}

{% tab title="422 Response" %}
A 422 response can be given in the following scenarios;

1. Account ID is incorrect

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "account_id": [
            "You do not have access to this account"
        ]
    }
}
```

2. Invalid mobile number

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "phone": [
            "The phone must be at least 10 characters."
        ]
    }
}
```

{% endtab %}
{% endtabs %}

#### Name search

A contact can be searched for by;

* First name
* Surname

If either of these are left blank (i.e. just John searched for), an array of contacts matching that will be returned.

{% tabs %}
{% tab title="Request" %}

```json
{
    "account_id": 3,
    "name": {
        "first_name": "John",
        "last_name": "Smith"
    }
}
```

{% endtab %}

{% tab title="200 Response" %}

```json
{
    "allow_sms": false,
    "allow_email": true,
    "allow_call": false,
    "allow_snail_mail": false,
    "udfs": [],
    "units": [
        {
            "id": 14458,
            "name": "Head Office",
            "groups": [
                {
                    "id": 126832,
                    "name": "Football visitor"
                },
                {
                    "id": 126842,
                    "name": "Christmas Competition entry"
                }
            ]
        },
        {
            "id": 14478,
            "name": "London venue",
            "groups": [
                {
                    "id": 126778,
                    "name": "WIFI"
                }
            ]
        }
    ],
    "feedback": "https://api.airship.co.uk/v1/contact/51616336/feedback",
    "bookings": "https://api.airship.co.uk/v1/contact/51616336/bookings",
    "purchases": "https://api.airship.co.uk/v1/contact/51616336/purchases",
    "proof_of_presence": "https://api.airship.co.uk/v1/contact/51616336/pops",
    "id": 51616336,
    "gender": "M",
    "title": "Mr",
    "first_name": "John",
    "last_name": "Smith",
    "dob": "1984-11-27",
    "building_name": "",
    "building_num_street": "2 Test Way",
    "locality": "",
    "postcode": "L1 1AA",
    "city": "London",
    "country": "United Kingdom",
    "county": "",
    "mobile_number": "447816000001",
    "home_number": "",
    "preferred_method_id": "0",
    "work_number": "",
    "email": "John.Smith@airship.co.uk",
    "source_id": "134747",
    "membership_number": "",
    "membership_type": ""
}
```

{% endtab %}

{% tab title="422 Response" %}

1. Account ID is incorrect

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "account_id": [
            "You do not have access to this account"
        ]
    }
}
```

{% endtab %}
{% endtabs %}