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();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"
}'{
"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"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Update Contact
Updates the name, internal flag and/or labels of a contact — at least one is required. Name changes apply on Periskope only.
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();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"
}'{
"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"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Authorizations
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.
Path Parameters
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.
1"911111111111"
Body
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.
"John Doe"
Whether the contact is internal (e.g. a teammate). Messages from internal contacts are not flagged for response.
false
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.
"lead, priority"
Response
The updated contact
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.
Id of the organization the contact belongs to
"00000000-0000-0000-0000-000000000000"
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.
"911111111111@c.us"
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.
"John Doe"
WhatsApp username of the contact. null when the contact has not set one or it has not been synced yet.
"jane.doe"
Type of the WhatsApp account: 'user' for a personal account, 'business' for a business account. null when not yet synced.
"user"
Whether the number is registered on WhatsApp, as reported by the connected phone. null when not yet synced.
true
Whether the contact is saved in the connected phone's address book. null when not yet synced.
true
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.
false
true when the contact was created via the API or an import rather than synced from a phone. null for synced contacts.
true
URL of the contact's WhatsApp profile picture. null when the contact has no picture or it is not accessible.
"https://example.com/files/image.png"
Hex color assigned to the contact, used to render it in the dashboard. null when no color is assigned.
"#DC2626"
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.
Show child attributes
Show child attributes
{ "label-aaaaaaaaaaaa": true }
Names of the labels currently on the contact, resolved from label_ids
["lead"]
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.
[
"911111111111@c.us",
"120363000000000000@g.us"
]
When the contact record was last updated, as an ISO 8601 timestamp
"2026-01-15T09:30:00.000Z"
Was this page helpful?