---
title: "Contact association"
method: POST
path: "/api/contacts/associate"
tags: ["Contacts"]
---

# Contact association

`POST /api/contacts/associate`

## Request

- Base URL: `https://go.urbanairship.com`
- URL: `https://go.urbanairship.com/api/contacts/associate`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `http://oauth2.{domain}.com/token` scopes: `cnt`
- TypeScript: <https://skmtc.dev/airship/apis/airship-api/docs/api/contacts/associate/post.ts> (a function with typed inputs; its response is checked against the schema)

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

## Request body

- union
  - ChannelIdContactIdAssociation
    - `channel_id` string, uuid, required: The channel ID you want to associate with a contact.
    - `contact_id` string, required: A string value identifying the user, without leading or trailing whitespace.
    - `device_type` 'ios' | 'android' | 'amazon' | 'web' | 'open' | 'email' | 'sms': The device type of the channel.
  - EmailAddressContactIdAssociation
    - `contact_id` string, required: The existing contact.
    - `email_address` string, email, required: The email address you want to associate with a contact.

## Response `200`

The request was accepted. The `contact_id` is returned in the response.

- OkResponseObject: 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.
  - `ok` boolean, required: Success.
  - `operation_id` string, uuid: A unique string identifying the operations that modify resources. Use the operation ID to locate and track grouped operations (i.e., a batch push operation may generate multiple `push_id` strings, but a single `operation_id`) or operations that change an existing resource.

## Other responses

- `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.
- `401`: Authentication information (the app key and secret or bearer token) was either incorrect or missing.
- `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.
- `406`: Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

## Changes

- **2026-06-24** `38241778b0c1`: 1 breaking, 1 info
  - removed `subschema #1: Contact association payload with Channel ID, subschema #2: Contact association payload with email address` from the request body `oneOf` list
  - added `#/components/schemas/channelIdContactIdAssociation, #/components/schemas/emailAddressContactIdAssociation` to the request body `oneOf` list
  - …this revision’s changelog is incomplete
- **2026-02-20** `e2bd980cb50b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/contacts/associate/post.md)

---

[API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)