import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
});
async function main() {
const response = await client.contacts.createContact({
contact_id: '911111111111',
contact_name: 'John Doe',
});
console.log(response);
}
main();curl -X POST 'https://api.periskope.app/v1/contacts/create' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"contact_id": "911111111111",
"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
}Create Contact
Creates a contact, or updates the existing one with the same contact_id (upsert). contact_id must be a possible phone number.
import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
});
async function main() {
const response = await client.contacts.createContact({
contact_id: '911111111111',
contact_name: 'John Doe',
});
console.log(response);
}
main();curl -X POST 'https://api.periskope.app/v1/contacts/create' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"contact_id": "911111111111",
"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.
Body
Phone number of the contact: country code + number without symbols or spaces (e.g. 911111111111). A leading + and the @c.us suffix are also accepted. Must be a possible phone number — invalid numbers are rejected with a 422.
1"911111111111"
Name to save for the contact. Stored as the Periskope name, which takes precedence over the WhatsApp-synced names — it is not changed on the phone itself.
1"John Doe"
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. Omit, or pass null or an empty string, to apply no labels — the labels of an already existing contact are left unchanged.
"lead, priority"
Whether to mark the contact as internal (e.g. a teammate). Messages from internal contacts are not flagged for response. When omitted the flag is left unset.
false
Response
The created 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?