# 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.

Endpoint: POST /tags
Version: 2.15
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)
    Intercom API version.By default, it's equal to the version set in the app package.
    Enum: "1.0", "1.1", "1.2", "1.3", "1.4", "2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14", "2.15", "Preview"

## Request fields (application/json):

  - `body` ((Create or Update Tag Request Payload (object)) or Tag Company Request Payload (object) or Untag Company Request Payload (object) or Tag Users Request Payload (object)) — one of:
    - Create or Update Tag Request Payload:
      - `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.
        Example: "Independent"
      - `id` (string)
        The id of tag to updates.
        Example: "656452352"
    - Tag Company Request Payload:
      - `name` (string, required)
        The name of the tag, which will be created if not found.
        Example: "Independent"
      - `companies` (array, required)
        The id or company_id of the company can be passed as input parameters.
      - `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"
    - Untag Company Request Payload:
      - `name` (string, required)
        The name of the tag which will be untagged from the company
        Example: "Independent"
      - `companies` (array, required)
        The id or company_id of the company can be passed as input parameters.
      - `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.untag` (boolean)
        Always set to true
        Example: "true"
    - Tag Users Request Payload:
      - `name` (string, required)
        The name of the tag, which will be created if not found.
        Example: "Independent"
      - `users` (array, required)
      - `users.id` (string)
        The Intercom defined id representing the user.
        Example: "5f7f0d217289f8d2f4262080"

## 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"

## Response 400 fields (application/json):

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

  - `request_id` (string,null)
    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,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

  - `errors.field` (string,null)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: "email"