---
title: "Update contact tags and groups"
method: POST
path: "/contacts/by-phone/{phone}/memberships"
tags: ["Contacts"]
---

# Update contact tags and groups

`POST /contacts/by-phone/{phone}/memberships`

## Request

- Base URL: `https://api.textla.com/v1`
- URL: `https://api.textla.com/v1/contacts/by-phone/{phone}/memberships`
- Auth: HTTP bearer

Adds and removes tags and groups on an existing contact addressed by its E.164 phone number. The API resolves the current contact and ETag, merges each requested bucket case-insensitively, and applies the result with an optimistic PATCH; existing memberships are not wiped. Supply at least one add or remove value. A concurrent change between lookup and write returns 412.

## Path parameters

- `phone` string, required: E.164 phone number identifying the contact

## Request body

- union
  - object
    - `tags` object, required
      - `add` string[], nullable, required: Values to add, preserving request order
      - `remove` string[], nullable: Values to remove, matched case-insensitively
    - `$schema` string, uri: A URL to the JSON Schema for this object.
    - `groups` MembershipChanges
      - `add` string[], nullable: Values to add, preserving request order
      - `remove` string[], nullable: Values to remove, matched case-insensitively
  - object
    - `tags` object, required
      - `add` string[], nullable: Values to add, preserving request order
      - `remove` string[], nullable, required: Values to remove, matched case-insensitively
    - `$schema` string, uri: A URL to the JSON Schema for this object.
    - `groups` MembershipChanges
      - `add` string[], nullable: Values to add, preserving request order
      - `remove` string[], nullable: Values to remove, matched case-insensitively
  - object
    - `groups` object, required
      - `add` string[], nullable, required: Values to add, preserving request order
      - `remove` string[], nullable: Values to remove, matched case-insensitively
    - `$schema` string, uri: A URL to the JSON Schema for this object.
    - `tags` MembershipChanges
      - `add` string[], nullable: Values to add, preserving request order
      - `remove` string[], nullable: Values to remove, matched case-insensitively
  - object
    - `groups` object, required
      - `add` string[], nullable: Values to add, preserving request order
      - `remove` string[], nullable, required: Values to remove, matched case-insensitively
    - `$schema` string, uri: A URL to the JSON Schema for this object.
    - `tags` MembershipChanges
      - `add` string[], nullable: Values to add, preserving request order
      - `remove` string[], nullable: Values to remove, matched case-insensitively

## Response `200`

OK

- Contact
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `account_id` string, required
  - `birth_date` string, nullable, required
  - `carrier` string, nullable, required
  - `city` string, nullable, required
  - `company` string, nullable, required
  - `contact_type` string, required
  - `country` string, nullable, required
  - `created_at` integer, required: When the contact record was created, as milliseconds since the Unix epoch
  - `custom_fields` CustomFieldValue[], nullable, required
    - `field_id` string
    - `name` string
    - `value` unknown, required
  - `email` string, nullable, required
  - `first_name` string, nullable, required
  - `groups` string[], nullable, required
  - `id` integer, required
  - `keywords` string[], nullable, required
  - `last_active_at` integer, nullable, required: When the contact was last active (used for aging), as milliseconds since the Unix epoch. Null when never recorded
  - `last_communicated_at` integer, nullable, required: When a message was last sent to this contact, as milliseconds since the Unix epoch. Null until the first send
  - `last_name` string, nullable, required
  - `location` Location, required
    - `lat` number, double, required
    - `lon` number, double, required
  - `marked_invalid_at` integer, nullable, required: When the contact's phone number was marked invalid (for example, after a hard delivery failure), as milliseconds since the Unix epoch. Null while the number is considered valid
  - `opted_in_at` integer, nullable, required: When the contact opted in to messaging, as milliseconds since the Unix epoch. Null if the contact has never opted in
  - `opted_out_at` integer, nullable, required: When the contact opted out of messaging, as milliseconds since the Unix epoch. Null while the contact is opted in. A non-null value means the contact must not be messaged
  - `phone` string, required
  - `postal_code` string, nullable, required
  - `signed_up_at` integer, nullable, required: When the contact signed up, as milliseconds since the Unix epoch. Null when not provided
  - `soft_opted_out_at` integer, nullable, required: When the contact was soft opted out, as milliseconds since the Unix epoch. Null while the contact is not soft opted out
  - `state` string, nullable, required
  - `street` string, nullable, required
  - `tags` string[], nullable, required
  - `updated_at` integer, required: When the contact record was last changed, as milliseconds since the Unix epoch

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `412`: Precondition Failed
- `422`: Unprocessable Entity
- `500`: Internal Server Error
- `502`: Bad Gateway
- `503`: Service Unavailable
- `504`: Gateway Timeout

---

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