Contacts

Manage Contacts and query for subscription lists, channels, named users, and attributes associated with a Contact.

Contact association

Associate a channel, email address, or MSISDN with a Contact. The contact_id is created if it does not already exist.

POST /api/contacts/associate

Note

If the channel_id, email_address, or msisdn is already associated with a contact_id, this operation will do nothing and return a 200 status code and the existing contact_id.

Security:

oauth2Token : cnt

Request body:

Contact association requires a channel_id, email_address, or msisdn. Do not provide more than one identifier type in the same request. You can associate up to 100 Channel IDs to a Contact.

Content-Type: application/json
One of
- Contact association payload with Channel ID object
  OBJECT PROPERTIES
  - channel_id stringREQUIRED
    The Channel ID you want to associate with a Contact.
    Format: uuid
    Example: 9c36e8c7-5a73-47c0-9716-99fd3d4197d5
  - contact_id stringREQUIRED
    A string value identifying the user, without leading or trailing whitespace.
    Min length: 1, Max length: 128
    Example: john_doe
  - device_type string
    The device type of the channel.
    Possible values: ios, android, amazon, web, open, email, sms
- Contact association payload with email address object
  OBJECT PROPERTIES
  - contact_id stringREQUIRED
    The existing Contact.
    Min length: 1, Max length: 128
    Example: john_doe
  - email_address stringREQUIRED
    The email address you want to associate with a Contact.
    Format: email
    Example: user@example.com

Responses

200
The request was accepted. The contact_id is returned in the response.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OK response
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Contact disassociation

Disassociates channel from a Contact with the option of also opting out. You can identify a channel by MSISDN, email address, or Channel ID.

Jump to examples ↓

POST /api/contacts/disassociate/{contact_id}

Security:

oauth2Token : cnt

Path parameters:

contact_id stringREQUIRED
The Contact ID to disassociate from a channel.

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- channel_id string
  The Channel ID to disassociate from the Contact.
  Format: uuid
  Example: {{channel_id}}
- channel_type stringREQUIRED
  The type of channel.
  Possible values: sms, email, ios, android, amazon, web, open
- email_address string
  The email address to disassociate from the Contact.
- msisdn string
  The mobile phone number to disassociate from the Contact. Must be numeric characters only, without leading zeros. 15 digits maximum.
  Max length: 15
- opt_out boolean
  Optional. True if the channel is to be opted out; otherwise false.
- sender string
  A long or short code the app is configured to send from. For example, 12345.

Responses

200
The request was accepted.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - channel_id string
    Identifies the existing unique Channel ID.
    Format: uuid
    Example: ef625038-70a3-41f1-826f-57bc11dd625a
  - contact string
    Identifies the existing unique Contact ID.
    Format: uuid
    Example: ef625038-70a3-41f1-826f-57bc11dd625a
  - ok boolean
    Success.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/contacts/disassociate/eed87e83-2f2f-4919-bcb0-8c620e0fae40 HTTP/1.1
Authorization: Bearer <contactJWTToken>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "channel_type": "sms",
  "channel_id": "c8d58c64-7eb5-40ad-ad51-d39e05335c48"
}

POST /api/contacts/disassociate/eed87e83-2f2f-4919-bcb0-8c620e0fae40 HTTP/1.1
Authorization: Bearer <contactJWTToken>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "channel_type": "sms",
  "sender": "1234",
  "msisdn": "15035551234"
}

POST /api/contacts/disassociate/eed87e83-2f2f-4919-bcb0-8c620e0fae40 HTTP/1.1
Authorization: Bearer <contactJWTToken>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "channel_type": "email",
  "email_address": "abc@example.com"
}

POST /api/contacts/disassociate/eed87e83-2f2f-4919-bcb0-8c620e0fae40 HTTP/1.1
Authorization: Bearer <contactJWTToken>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "channel_type": "email",
  "email_address": "abc@example.com",
  "opt_out": true
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true,
    "contact": "eed87e83-2f2f-4919-bcb0-8c620e0fae40",
    "channel_id": "c8d58c64-7eb5-40ad-ad51-d39e05335c48"
}

Contacts tags

Add, remove, or set tags on a Contact. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.

POST /api/contacts/tags/

Important

A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response. We support up to 1,000 tags per Contact. Adding more than 1,000 tags per Contact can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1,000 tags per Contact, and they will help you find an alternative.

Security:

oauth2Token : cnt

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- add object<Tag Group object>
  Add the list of tags to the Contacts, but do not remove any. If the tags are already present, they are not modified.
  Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.
  A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.
- audience objectREQUIRED
  The Contacts you want to associate/disassociate tags with.
  OBJECT PROPERTIES
  - contact_id array[string]
    Min items: 1, Max items: 1000
- remove object<Tag Group object>
  Remove the list of tags from the Contacts, but do not remove any others. If the tags are not currently present, nothing happens.
  Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.
  A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.
- set object<Tag Group object>
  Set these tags for the audience. Any tags previously associated with the audience tags that are not in this current list are removed.
  Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.
  A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

200
If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.
Response body:
- Content-Type: application/json
  Body may contain warnings about portions of the request which were not processed.
  OBJECT PROPERTIES
  - ok booleanREQUIRED
    Set to true when status code is 200.
  - tag_warnings string
    Warnings encountered when processing tags for this Contact.
400
Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Look up Contact ID by Channel ID

Looks up a Contact ID for the given Channel ID.

Jump to examples ↓

GET /api/contacts/lookup/channel/{channel_id}

Security:

Path parameters:

channel_id stringREQUIRED
The Channel ID for which to retrieve the associated Contact ID.

Responses

200
The request was accepted.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - contact_id stringREQUIRED
    The resolved Contact ID.
    Format: uuid
  - is_anonymous booleanREQUIRED
    Specifies whether the Contact is anonymous or not.
  - ok booleanREQUIRED
    Set to true when status code is 200.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
Response body:
- Content-Type: application/vnd.urbanairship+json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

GET /api/contacts/lookup/channel/164c3a13-9c75-4ea9-be2c-1bed2c97f9c3 HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "contact_id": "7c24ebdd-ec06-47d4-9a56-ced8611f5b52",
   "is_anonymous": false
}

Look up Contact ID by Named User ID

Looks up a Contact ID for the given Named User ID.

Jump to examples ↓

GET /api/contacts/lookup/named_user/{named_user_id}

Security:

Path parameters:

named_user_id stringREQUIRED
The URL-encoded Named User ID for which to retrieve the associated Contact ID.

Responses

200
The request was accepted.
Response body:
- Content-Type: application/json
  The Contact ID in the response will be based on these precedence rules:
  - From the Named User if it exists
  - From the channel if it is associated to an Anonymous Contact
  - From the payload if provided
  - Randomly generated
  OBJECT PROPERTIES
  - contact_id stringREQUIRED
    The resolved Contact ID.
    Format: uuid
  - ok booleanREQUIRED
    Set to true when status code is 200.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
Response body:
- Content-Type: application/vnd.urbanairship+json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

GET /api/contacts/lookup/named_user/90ae282f-f56e-4037-8174-482ef7e3e5f4 HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "contact_id": "7c24ebdd-ec06-47d4-9a56-ced8611f5b52"
}

Scoped Contact batch operations

Performs one or more scoped operations on a Contact in a single request. The body is a scoped array, and each item has a scope and one or more operations. Behavior matches the equivalent single-operation APIs. For each scope:

Subscription list operations are supported. You can subscribe and/or unsubscribe the Contact to/from subscription lists for that scope, which is the same behavior as the subscription list APIs.
Tag operations are not supported. If tags is present in any scoped item, the request is rejected with 400 and an error indicating that tags are not allowed in this context.

The following apply:

Set operations are not supported.
Failure to authorize on secure tags results in a 200 and warning.
Failure to find any valid tag groups results in a 200 and warning.
Failure to find any valid attributes results in a 200 and warning.

Jump to examples ↓

POST /api/contacts/scoped/{contact_id}

Note

If you are using a single-channel Preference Center created before October 10, 2022, that has not been migrated to user-level, use the /api/channels/subscription_lists endpoint to add or remove individual channels to/from your subscription list.

Important

The path parameter contact_id should be URL-encoded to ensure it is handled correctly.

Security:

Path parameters:

contact_id stringREQUIRED
A string (UUID) value identifying the Contact with no leading or trailing whitespace.

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- scoped array
  An array of scopes, tags, and subscription lists.

Responses

200
The request was accepted.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - ok booleanREQUIRED
    Whether the operation was successful.
  - subscription_list_warnings array[string]
    Any warnings related to subscription list operations.
  - tag_warnings array[string]
    Any warnings related to tag operations.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/contacts/scoped/77721a11-7ffa-4362-9bdb-f27ca891f9de HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "scoped": [{
    "scope": ["web", "email", "app"],
    "subscription_lists": {
      "subscribe": ["subscription_1", "subscription_2"],
      "unsubscribe": ["subscription_3"]
    }
  }]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

Set or remove attributes on a Contact

Set or remove attributes on a Contact.

A single request body may contain a set or remove field, or both, or a single set field. If both set and remove fields are present and the intersection of the attributes in these fields is not empty, then a 400 will be returned.

If an attribute request is partially valid, i.e., at least one attribute exists, Airship returns a 200 with a warning about the attributes that failed to update. The attributes listed in the warnings string will be in CSV format.

POST /api/contacts/attributes

Note

Airship returns a 200 with a warning if you attempt to set attributes on a Contact that does not exist.

Tip

If you wish to set attributes on multiple Contact at once, we recommend using /api/channels/attributes which supports an audience object in the request body.

Security:

oauth2Token : cnt

Request body:

Content-Type: application/json
array<Attributes Object>
Include an array of attributes objects in your request.

Responses

200
Success. If an attribute request is partially valid, i.e., at least one attribute exists, Airship returns a 200 with a warning string containing a CSV list of attributes that failed to update. Airship also returns a 200 with a warning if you attempt to set attributes on a contact_id, even if the contact_id does not exist.
Response body:
- Content-Type: application/json
  Body may contain warnings about portions of the request which were not processed.
  OBJECT PROPERTIES
  - ok boolean
    Set to true when status code is 200.
  - warnings string
    Warnings encountered when updating Contact attributes.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.