# Create or update a tag, Tag or untag companies, Tag contacts

You can use this endpoint to perform the following operations:
**1. Create a new tag:** You can create a new tag by passing in the tag name as specified in "Create or Update Tag Request Payload" described below.
**2. Update an existing tag:** You can update an existing tag by passing the id of the tag as specified in "Create or Update Tag Request Payload" described below.
**3. Tag Companies:** You can tag single company or a list of companies. You can tag a company by passing in the tag name and the company details as specified in "Tag Company Request Payload" described below. Also, if the tag doesn't exist then a new one will be created automatically.
**4. Untag Companies:** You can untag a single company or a list of companies. You can untag a company by passing in the tag id and the company details as specified in "Untag Company Request Payload" described below.
**5. Tag Multiple Users:** You can tag a list of users. You can tag the users by passing in the tag name and the user details as specified in "Tag Users Request Payload" described below.
Each operation will return a tag object.
Contacts and companies listed in `users` or `companies` that do not exist are skipped: they are left out of the `users` and `companies` arrays in the response and the request still succeeds. With `ids_to_add` it depends on `taggable_type`: a contact id that does not exist returns a 404, while a company id that does not exist is skipped. With `ids_to_add`, the `users` and `companies` arrays in the response are always empty, and a 404 still leaves the tag created or renamed.
Requires the `write_tags` or `write_users_companies` OAuth scope.

Endpoint: POST /tags
Version: 2.18
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)

## Request fields (application/json):

  - `name` (string, required)
    The name of the tag, which will be created if not found, or the new name for the tag if this is an update request. Names are case insensitive and can be at most 191 characters long. Creating a tag with a longer name returns a 400. When updating by `id`, a longer name or one that another tag already has returns 200 with the new name, but the tag keeps its old name.
    Example: Independent

  - `id` (string)
    The id of tag to updates.
    Example: 656452352

  - `ids_to_add` (array)
    The Intercom ids of the contacts or companies to apply the tag to. A contact id that does not exist returns a 404; a company id that does not exist is skipped. A 404 still leaves the tag created or renamed. The `users` and `companies` arrays in the response are always empty when this field is used.
    Example: ["536e564f316c83104c000020"]

  - `taggable_type` (string)
    Whether the ids in `ids_to_add` are contacts or companies. Defaults to `user`.
    Enum: "user", "company"

  - `name` (string, required)
    The name of the tag, which will be created if not found. Names can be at most 191 characters long.
    Example: Independent

  - `companies` (array, required)
    The id, company_id or name of the company can be passed as input parameters. Companies that cannot be found are skipped.

  - `companies.id` (string)
    The Intercom defined id representing the company.
    Example: 531ee472cce572a6ec000006

  - `companies.company_id` (string)
    The company id you have defined for the company.
    Example: 6

  - `companies.name` (string)
    The name of the company, used to look it up when neither `id` nor `company_id` is given.
    Example: Intercom

  - `name` (string, required)
    The name of the tag which will be untagged from the company. Names can be at most 191 characters long.
    Example: Independent

  - `users` (array, required)
    The id, user_id or email of the user can be passed as input parameters. Users that cannot be found are skipped.

  - `users.id` (string)
    The Intercom defined id representing the user.
    Example: 5f7f0d217289f8d2f4262080

  - `users.user_id` (string)
    The user id you have defined for the user, used to look it up when `id` is not given.
    Example: 25

  - `users.email` (string)
    The email address of the user, used to look it up when neither `id` nor `user_id` is given.
    Example: jane@example.com

  - `users.untag` (boolean)
    Set to true to remove the tag from this user instead of applying it.
    Example: true

## Response 200 fields (application/json):

  - `type` (string)
    value is "tag"
    Example: tag

  - `id` (string)
    The id of the tag
    Example: 123456

  - `name` (string)
    The name of the tag
    Example: Test tag

  - `users` (array)
    The users that were tagged or untagged.
    Example: []

  - `users.id` (string)
    The Intercom ID of the user.
    Example: 6329e838deab40166d1a53f7

  - `users.tagged` (boolean)
    Whether the user was tagged (true) or untagged (false).
    Example: true

  - `companies` (array)
    The companies that were tagged or untagged.
    Example: []

  - `companies.id` (string)
    The Intercom ID of the company.
    Example: 6329e838deab40166d1a5400

  - `companies.tagged` (boolean)
    Whether the company was tagged (true) or untagged (false).
    Example: true

## Response 400 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 404 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

