Write a contact

How to store a contact to Airship

Endpoint

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

Configuration

Field	Notes
account_id	The account ID represents the account that you are storing this contact to. If you are unsure of what your account ID is, ask our support team to confirm.
full_contact_object	Optional (defaults to True if not added) Boolean for if you want the full contact object returned when creating a contact. If set to false, only a contact ID will be returned in the response (making the request quicker), else if true or not added to the request, the full contact object will be returned
source_id	The source ID represents the source of this data, for example "Table Booking" or "WiFi". Usually our support team will advise on a predefined source ID to use. However, you can also create them on-the-fly by passing insource_name rather than source_id. We'll create a source of that name if one doesn't already exist.
units	Airship has predefined locations or "units" to store contacts for different physical locations. The units object represents which location you wish to store this contact to. You can fetch a list of units for your account using the account/unitsendpoint. You can pass in an array of units if you wish to store to more than one location.
groups > name	Groups can represent any predefined tag or segment for a contact. If you pass in a name, a group of that name will be created on that unit if it doesn't already exist. Alternatively, you can pass in an id for a pre existing group.
groups > folder_name	A folder_name can be specified for your group, allowing the data to be structured in folders via the API for easier segmentation / categorisation. If no folder is defined, the default folder will be applied
gender	Value is either "M" for Male or "F" for Female. For non-binary / other, leave blank.

Basic contact payload

Body

{
  "account_id": 3,
  "full_contact_object": false,
  "first_name": "John",
  "last_name": "Smith",
  "mobile_number": "07780704261",
  "gender": "M",
  "email": "[e-mail]",
  "dob": "1982-01-16",
  "source_id": 125795,
  "allow_sms": true,
  "allow_email": true,
  "units": [
    {
      "id": 8775,
      "groups": [
        {
          "name": "My First Group",
          "folder_name": "Web signups"
        }
      ]
    }
  ]
}

Response

{
    "allow_sms": "1",
    "allow_email": "1",
    "allow_call": "",
    "allow_snail_mail": "",
    "udfs": [],
    "units": [
        {
            "id": 8775,
            "name": "Sheffield",
            "groups": [
                {
                    "id": 121981,
                    "name": "My First Group"
                }
            ]
        }
    ],
    "feedback": "https://api.airship.co.uk/v1/contact/44431435/feedback",
    "purchases": "https://api.airship.co.uk/v1/contact/44431435/purchases",
    "id": 44431435,
    "gender": "M",
    "title": "",
    "first_name": "John",
    "last_name": "Smith",
    "dob": "1982-01-16",
    "building_name": "",
    "building_num_street": "",
    "locality": "",
    "postcode": "",
    "city": "",
    "country": "",
    "county": "",
    "mobile_number": "447780704261",
    "home_number": "",
    "preferred_method_id": "0",
    "work_number": "",
    "email": "[e-mail]",
    "source_id": "125795",
    "membership_number": "",
    "membership_type": ""
}

Using rules

When creating a contact, you can also opt to use one of our "rules". These have been created to allow you to control how your contact will be stored in Airship, and can help take away the strain of dealing with extra logic to handle these scenarios within your app.

Rule	Description
discard_invalid_data	We'll discard any data that doesn't pass our validation, and store the rest. For example, if you pass in an invalid mobile_number but a valid email, we'll discard the mobile but store the email, along with the rest of the data. Note that we require at least a valid email or mobile to be able to store a contact record.
historic_data	If you pass in this rule, if the contact already exists on Airship, the consent/opt-in flags will be preserved regardless of what is passed in for the opt in values.
preserve_consent	If you pass in this rule, if the contact already exists on Airship, the consent/opt-in flags will be preserved when passing in 'N' opt in values.
detach_existing_groups	If you pass in this rule, all existing groups will be removed from the contact record, and they will be only added to the group passed in the request
update_only	If you pass in this rule, it will only append / update existing Airship contact profiles with any information passed, and never create a new contact record

Example using "rules":

"account_id": 3,
"email": "[e-mail]",
//...etc...

"rules": [
    {
      "rule_name": "preserve_consent"
    },
    {
      "rule_name": "discard_invalid_data"
    }
]

Contact notes

Contact notes are optional, and can be appended to a contact record. A note cannot be amended once added, and we will add a new note for every request we receive with a notes field

Field	Notes
text	Notes string that you want to store. Max 500 character length
created_at	Date/time of note creation. If no created_at field is added, it will default to the timestamp the request was received Optional

"account_id": 3,
"email": "[e-mail]",
//...etc...

    "notes": [
        {
            "text": "I liked the cocktails!",
            "created_at": "2024-02-10 15:10:00"
        }
    ]

Custom fields

As well as the standard fields documented on our API Reference, we can also store custom values to User Defined Fields (UDFs). These have to be pre-created in the Airship dashboard and you will need to know the UDFID of the field you wish to write data to.

UDFs can be passed in as an array as part of your payload.

"account_id": 3,
"email: "[e-mail]",
//...etc...

"udfs": [
    {
      "id": 1234,
      "data": "some text"
    },
    {
      "id": 5678,
      "data": "2021-05-01"
    }
  ]

Mobile number validation

Mobile numbers are validated for an accepted prefix, which can be any of the following:

4471, 4472, 4473, 4474, 4475, 4476, 4477, 4478, 4479, 071, 072, 073, 074, 075, 076, 077, 078, 079

Email validation

Emails are validated to contain a @ and a . and are also checked against a list of domains with valid MX records, to protect against commonly mistyped or fake domains.