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

# The Contact Object

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

<ResponseExample>
  ```json The Contact Object theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

**Attributes**

<ParamField path="org_id" type="string">
  Id of the organization the contact belongs to
</ParamField>

<ParamField path="contact_id" type="string">
  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.
</ParamField>

<ParamField path="contact_name" type="string">
  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.
</ParamField>

<ParamField path="username" type="string">
  WhatsApp username of the contact. null when the contact has not set one or it has not been synced yet.
</ParamField>

<ParamField path="contact_type" type="string">
  Type of the WhatsApp account: 'user' for a personal account, 'business' for a business account. null when not yet synced.
</ParamField>

<ParamField path="is_wa_contact" type="boolean">
  Whether the number is registered on WhatsApp, as reported by the connected phone. null when not yet synced.
</ParamField>

<ParamField path="is_my_contact" type="boolean">
  Whether the contact is saved in the connected phone's address book. null when not yet synced.
</ParamField>

<ParamField path="is_internal" type="boolean">
  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.
</ParamField>

<ParamField path="is_imported" type="boolean">
  true when the contact was created via the API or an import rather than synced from a phone. null for synced contacts.
</ParamField>

<ParamField path="contact_image" type="string">
  URL of the contact's WhatsApp profile picture. null when the contact has no picture or it is not accessible.
</ParamField>

<ParamField path="contact_color" type="string">
  Hex color assigned to the contact, used to render it in the dashboard. null when no color is assigned.
</ParamField>

<ParamField path="label_ids" type="object">
  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.
</ParamField>

<ParamField path="labels" type="string[]">
  Names of the labels currently on the contact, resolved from label\_ids
</ParamField>

<ParamField path="chat_ids" type="string[]">
  Ids of the chats the contact participates in — the 1-1 chat (\<countrycode>\<number>@c.us) and any group chats (\<group-id>@g.us) shared with the workspace. Contains a single null entry when the contact is not a participant of any chat.
</ParamField>

<ParamField path="updated_at" type="string">
  When the contact record was last updated, as an ISO 8601 timestamp
</ParamField>


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