> ## 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 > Updates the name, internal flag and/or labels of a contact — at least one is required. Name changes apply on Periskope only. ## OpenAPI ````yaml api-reference/openapi-generated.json PATCH /v1/contacts/{contact_id} 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/{contact_id}: patch: tags: - Contacts summary: Update a contact description: >- Updates the name, internal flag and/or labels of a contact — at least one is required. Name changes apply on Periskope only. operationId: updateContact parameters: - schema: type: string minLength: 1 description: >- Phone number of the contact: country code + number without symbols or spaces (e.g. 911111111111). The full WhatsApp id (911111111111@c.us) is also accepted. example: '911111111111' required: true description: >- Phone number of the contact: country code + number without symbols or spaces (e.g. 911111111111). The full WhatsApp id (911111111111@c.us) is also accepted. name: contact_id in: path requestBody: content: application/json: schema: type: object properties: contact_name: type: string description: >- New name for the contact. Updated on Periskope only (stored as the Periskope name) — the name on the phone is not changed. Pass an empty string to clear the Periskope name and fall back to the WhatsApp-synced name. example: John Doe is_internal: type: boolean description: >- Whether the contact is internal (e.g. a teammate). Messages from internal contacts are not flagged for response. example: false labels: type: string 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. example: lead, priority responses: '200': description: The updated contact content: application/json: schema: $ref: '#/components/schemas/Contact' examples: default: summary: Response body value: org_id: 00000000-0000-0000-0000-000000000000 contact_id: 911111111111@c.us contact_name: John Doe username: jane.doe contact_type: user is_wa_contact: true is_my_contact: true is_internal: false is_imported: true contact_image: https://example.com/files/image.png contact_color: '#DC2626' label_ids: label-aaaaaaaaaaaa: true labels: - lead chat_ids: - 911111111111@c.us - 120363000000000000@g.us updated_at: '2026-01-15T09:30:00.000Z' '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.updateContact({ contact_id: '911111111111', contact_name: 'John Doe', }); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X PATCH 'https://api.periskope.app/v1/contacts/911111111111' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "contact_name": "John Doe" }' components: schemas: Contact: type: object properties: org_id: type: string format: uuid description: Id of the organization the contact belongs to example: 00000000-0000-0000-0000-000000000000 contact_id: type: string description: >- Unique id of the contact within the org: country code + number suffixed with @c.us. Use the number part (with or without the suffix) wherever a contact_id parameter is expected. example: 911111111111@c.us contact_name: type: string description: >- Display name of the contact — the Periskope-set name when one was saved via the API or dashboard, otherwise the WhatsApp verified name, address-book name or push name. null when no name is known from any source. example: John Doe username: type: string description: >- WhatsApp username of the contact. null when the contact has not set one or it has not been synced yet. example: jane.doe contact_type: type: string description: >- Type of the WhatsApp account: 'user' for a personal account, 'business' for a business account. null when not yet synced. example: user is_wa_contact: type: boolean description: >- Whether the number is registered on WhatsApp, as reported by the connected phone. null when not yet synced. example: true is_my_contact: type: boolean description: >- Whether the contact is saved in the connected phone's address book. null when not yet synced. example: true is_internal: type: boolean description: >- Whether the contact is marked as internal (e.g. a teammate). Messages from internal contacts are not flagged for response. null when the flag was never set. example: false is_imported: type: boolean description: >- true when the contact was created via the API or an import rather than synced from a phone. null for synced contacts. example: true contact_image: type: string description: >- URL of the contact's WhatsApp profile picture. null when the contact has no picture or it is not accessible. example: https://example.com/files/image.png contact_color: type: string description: >- Hex color assigned to the contact, used to render it in the dashboard. null when no color is assigned. example: '#DC2626' label_ids: type: object additionalProperties: type: boolean description: >- Map of label_id to boolean for the labels on the contact. Labels on a contact are shared with its 1-1 chat. An empty object when the contact has no labels. example: label-aaaaaaaaaaaa: true labels: type: array items: type: string description: >- Names of the labels currently on the contact, resolved from label_ids example: - lead chat_ids: type: array items: type: string description: >- Ids of the chats the contact participates in — the 1-1 chat (@c.us) and any group chats (@g.us) shared with the workspace. Contains a single null entry when the contact is not a participant of any chat. example: - 911111111111@c.us - 120363000000000000@g.us updated_at: type: string description: When the contact record was last updated, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' description: >- A WhatsApp contact known to the workspace — synced from a connected phone's address book and chats, or created via the API. Contacts belong to the org as a whole, not to a single phone. Labels on a contact are shared with the contact's 1-1 chat. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. 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.