---
title: "Scoped contact batch operations"
method: POST
path: "/api/contacts/scoped/{contact_id}"
tags: ["Contacts"]
---

# Scoped contact batch operations

`POST /api/contacts/scoped/{contact_id}`

## Request

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

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.

## Path parameters

- `contact_id` string, uuid, required

## Request body

- object
  - `scoped` ContactsScopedBatchItem[]: An array of scopes, tags, and subscription lists.
    - `scope` Scopes[], required
    - `subscription_lists` ContactSubscriptionListsObject: Defines the subscription list changes.
      - `subscribe` string[]: Subscribe to the specified subscription list identifier.
      - `unsubscribe` string[]: Unsubscribe the specified subscription list identifier.
    - `tags` NamedUserTags[]
      - `add` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/).
      - `remove` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/).
      - `set` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/).

## Response `200`

The request was accepted.

- ContactsScopedBatchResponse
  - `ok` boolean, required: Whether the operation was successful.
  - `subscription_list_warnings` string[]: Any warnings related to subscription list operations.
  - `tag_warnings` string[]: Any warnings related to tag operations.

## 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-02-20** `e2bd980cb50b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/contacts/scoped/:contact_id/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)