> ## Documentation Index
> Fetch the complete documentation index at: https://docs.periskope.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Contact Labels

> Sets the labels of one or more contacts; label names that do not exist yet are created automatically. Pass null or an empty string as labels to remove every label.



## OpenAPI

````yaml api-reference/openapi-generated.json PATCH /v1/contacts/labels
openapi: 3.0.3
info:
  title: Periskope API
  version: 1.0.0
  description: >-
    Periskope external API.


    Responses use a flat, unwrapped shape: most endpoints return the resource at
    the top level, and list endpoints return a wrapper object with pagination
    inline (e.g. `{ from, to, count, chats: [...] }`). The documented response
    schemas describe these shapes directly.
servers:
  - url: https://api.periskope.app
security:
  - bearerAuth: []
paths:
  /v1/contacts/labels:
    patch:
      tags:
        - Contacts
      summary: Update the labels of multiple contacts
      description: >-
        Sets the labels of one or more contacts; label names that do not exist
        yet are created automatically. Pass null or an empty string as labels to
        remove every label.
      operationId: updateContactLabels
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                contact_ids:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
                  description: >-
                    Phone numbers of the contacts to update: country code +
                    number without symbols or spaces (e.g. 911111111111). The
                    @c.us suffix is also accepted.
                  example:
                    - '911111111111'
                    - '911111111111'
                labels:
                  type: string
                  nullable: true
                  description: >-
                    Comma-separated list of labels to put on the contact (e.g.
                    'lead, priority'). Labels are matched case-insensitively and
                    labels that do not exist yet are created automatically. This
                    replaces all current labels of the contact — pass the full
                    desired list. Pass null or an empty string to remove every
                    label from the contacts.
                  example: lead, priority
              required:
                - contact_ids
                - labels
      responses:
        '204':
          description: Labels updated — no content
        '401':
          description: Invalid, expired or missing API token
          content:
            application/json:
              examples:
                error:
                  summary: Invalid, expired or missing API token
                  value:
                    code: UNAUTHORIZED_ERROR
                    message: Invalid bearer auth token
                    status: 401
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: UNAUTHORIZED_ERROR
                  message:
                    type: string
                    example: Invalid bearer auth token
                  status:
                    type: integer
                    example: 401
                example:
                  code: UNAUTHORIZED_ERROR
                  message: Invalid bearer auth token
                  status: 401
        '422':
          description: Request validation failed
          content:
            application/json:
              examples:
                error:
                  summary: Request validation failed
                  value:
                    code: VALIDATION_ERROR
                    message: Request validation failed
                    status: 422
                    fields:
                      body.chat_id:
                        message: chat_id is required
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: VALIDATION_ERROR
                  message:
                    type: string
                    example: Request validation failed
                  status:
                    type: integer
                    example: 422
                  fields:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        message:
                          type: string
                        value: {}
                    example:
                      body.chat_id:
                        message: chat_id is required
                example:
                  code: VALIDATION_ERROR
                  message: Request validation failed
                  status: 422
                  fields:
                    body.chat_id:
                      message: chat_id is required
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              examples:
                error:
                  summary: Rate limit exceeded
                  value:
                    code: RATE_LIMIT_ERROR
                    message: You can only make 100 requests per second
                    status: 429
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: RATE_LIMIT_ERROR
                  message:
                    type: string
                    example: You can only make 100 requests per second
                  status:
                    type: integer
                    example: 429
                example:
                  code: RATE_LIMIT_ERROR
                  message: You can only make 100 requests per second
                  status: 429
        '500':
          description: Internal server error
          content:
            application/json:
              examples:
                error:
                  summary: Internal server error
                  value:
                    code: UNKNOWN_ERROR
                    message: Internal server error
                    status: 500
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: UNKNOWN_ERROR
                  message:
                    type: string
                    example: Internal server error
                  status:
                    type: integer
                    example: 500
                example:
                  code: UNKNOWN_ERROR
                  message: Internal server error
                  status: 500
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: typescript
          label: TypeScript
          source: |-
            import { PeriskopeApi } from '@periskope/periskope-client';

            const client = new PeriskopeApi({
              authToken: 'YOUR_API_KEY',
            });

            async function main() {
              const response = await client.contacts.updateContactLabels({
                contact_ids: [
                  '911111111111',
                  '911111111111',
                ],
                labels: 'lead, priority',
              });
              console.log(response);
            }

            main();
        - lang: bash
          label: cURL
          source: |-
            curl -X PATCH 'https://api.periskope.app/v1/contacts/labels' \
              -H 'Authorization: Bearer YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "contact_ids": [
                  "911111111111",
                  "911111111111"
                ],
                "labels": "lead, priority"
              }'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Periskope API token, sent as `Authorization: Bearer <token>`.
        Generate one from the Periskope dashboard under **Settings → API &
        Webhooks**. API access requires an active Pro or Enterprise plan.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.