Write a contact
How to store a contact to Airship

Endpoint

1
https://api.airship.co.uk/v1/contact
Copied!

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.
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
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.
gender
Value is either "M" for Male or "F" for Female. For non-binary / other, leave blank.

Basic contact payload

Body
Response
1
{
2
"account_id": 3,
3
"first_name": "John",
4
"last_name": "Smith",
5
"mobile_number": "07780704261",
6
"gender": "M",
7
"email": "[email protected]",
8
"dob": "1982-01-16",
9
"source_id": 125795,
10
"allow_sms": true,
11
"allow_email": true,
12
"units": [
13
{
14
"id": 8775,
15
"groups": [
16
{
17
"name": "My First Group"
18
}
19
]
20
}
21
]
22
}
Copied!
1
{
2
"allow_sms": "1",
3
"allow_email": "1",
4
"allow_call": "",
5
"allow_snail_mail": "",
6
"udfs": [],
7
"units": [
8
{
9
"id": 8775,
10
"name": "Sheffield",
11
"groups": [
12
{
13
"id": 121981,
14
"name": "My First Group"
15
}
16
]
17
}
18
],
19
"feedback": "https://api.airship.co.uk/v1/contact/44431435/feedback",
20
"purchases": "https://api.airship.co.uk/v1/contact/44431435/purchases",
21
"id": 44431435,
22
"gender": "M",
23
"title": "",
24
"first_name": "John",
25
"last_name": "Smith",
26
"dob": "1982-01-16",
27
"building_name": "",
28
"building_num_street": "",
29
"locality": "",
30
"postcode": "",
31
"city": "",
32
"country": "",
33
"county": "",
34
"mobile_number": "447780704261",
35
"home_number": "",
36
"preferred_method_id": "0",
37
"work_number": "",
38
"email": "[email protected]",
39
"source_id": "125795",
40
"membership_number": "",
41
"membership_type": ""
42
}
Copied!

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.
Example using "rules":
1
"account_id": 3,
2
3
//...etc...
4
5
"rules": [
6
{
7
"rule_name": "preserve_consent"
8
},
9
{
10
"rule_name": "discard_invalid_data"
11
}
12
]
Copied!

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.
1
"account_id": 3,
2
3
//...etc...
4
5
"udfs": [
6
{
7
"id": 1234,
8
"data": "some text"
9
},
10
{
11
"id": 5678,
12
"data": "2021-05-01"
13
}
14
]
Copied!

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.