Write a contact

How to store a contact to Airship







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.


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


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.


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


Value is either "M" for Male or "F" for Female. For non-binary / other, leave blank.

Basic contact payload

  "account_id": 3,
  "full_contact_object": false,
  "first_name": "John",
  "last_name": "Smith",
  "mobile_number": "07780704261",
  "gender": "M",
  "email": "johnsmith@airship.co.uk",
  "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"

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.




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.


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.


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.


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.

Example using "rules":

"account_id": 3,
"email": "johnsmith@airship.co.uk",

"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



Notes string that you want to store. Max 500 character length


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": "johnsmith@gmail.com",

    "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: "johnsmith@gmail.com",

"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.

Last updated