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

GET

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

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.

Request

{
    "account_id": 3,
    "email": "[e-mail]"
}

200 Response

{
    "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": "[e-mail]",
    "source_id": "134747",
    "membership_number": "",
    "membership_type": ""
}

422 Response

A 422 response can be given in the following scenarios;

1. Account ID is incorrect

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

2. Invalid email address

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

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.

Request

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

200 Response

{
    "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": "[e-mail]",
    "source_id": "134747",
    "membership_number": "",
    "membership_type": ""
}

422 Response

A 422 response can be given in the following scenarios;

1. Account ID is incorrect

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

1. Invalid mobile number

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

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.

Request

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

200 Response

{
    "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": "[e-mail]",
    "source_id": "134747",
    "membership_number": "",
    "membership_type": ""
}

422 Response

1. Account ID is incorrect

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