---
title: Contacts
summary: 'A contact is a named external person or company with one or more phone numbers. Contacts identify incoming callers, can route their calls differently, and can be blocked entirely.'
section: features
tags:
  - crud
  - telephony
updated: '2026-08-12'
---

> A **contact** is a named external person or company with one or more phone numbers. The PBX matches incoming caller IDs against the contact list and surfaces the contact's name, company, and VIP status on the answering phone.

## Overview

Contacts make the difference between "Anonymous caller" and "John Smith - Acme Corp" on the answering user's screen. They are an inbound-side feature: a contact needs at least one phone number to be matched, and beyond identification they drive two optional behaviors.

- **Global block** - reject all of a contact's inbound calls tenant-wide.
- **Handling strategy** - route a contact's calls to a specific destination instead of the called number's normal flow.

Contacts can be shared across the tenant or private to one user. Shared contacts require the *manage global contacts* permission.

## What it does

The **handling strategy** overrides routing when the contact calls in from outside (internal calls are unaffected).

| Strategy | When to use |
|---|---|
| **Default** | Identification only, no routing change. The standard case for almost all contacts. |
| **Call flow** | Multi-step routing for important contacts, for example a VIP greeting then a priority queue. |
| **Extension** | Send the contact straight to a specific desk regardless of the number they dialled. |
| **User** | VIP-to-account-manager routing. The user's phones, twinning, and DND rules apply. |
| **SIP device** | Route to a shared phone or kiosk not owned by one user. |

The **VIP flag** lets a contact bypass Do not disturb on the called user. It requires the user to also hold the *VIP* permission, granted by an administrator.

> [!WARNING]
> Block applies tenant-wide, not per-user. Once a contact is blocked, no one on the tenant receives their calls.

## See also

- [Phone numbers](phone_numbers.md) - the DIDs whose default routing the contact handling strategy overrides.
- [Call flows](call_flows.md) - the routing destination for the *Call flow* handling strategy.
- [Users](users.md) - the VIP permission lives on the user receiving the call.

```yaml fields
name1:
  label: 'First name'
  api: name1
  tab: General
  hint: "The contact's first name. At least one name field is required."
name2:
  label: 'Last name'
  api: name2
  tab: General
  hint: "The contact's last name."
vip:
  label: VIP
  tab: General
  hint: 'Marks the contact as VIP. When on, this contact can ring through Do not disturb on the receiving user, provided that user also holds the VIP permission.'
email:
  label: E-mail
  api: email
  tab: General
  hint: "The contact's email address, shown in call history."
company_name:
  label: 'Company name'
  api: company_name
  tab: General
  hint: 'The company or organization the contact belongs to. Shown on the answering phone and in list filters.'
groups:
  label: 'Visible only to these groups'
  api: groups
  tab: General
  hint: 'When groups are selected, this contact is only visible to users in those groups. Leave empty to make the contact visible to everyone.'
contactPhoneNumbers:
  label: 'Phone numbers'
  api: contactPhoneNumbers
  tab: General
  hint: 'Phone numbers for this contact. Each number has a type, an optional label, an optional speed dial code, and an optional call flow for routing incoming calls from that number.'
department:
  label: Department
  api: department
  tab: General
  hint: "The department within the contact's organization. Shown in list filters."
job_title:
  label: 'Job title'
  api: job_title
  tab: General
  hint: "The contact's job title or role."
notes:
  label: Notes
  api: notes
  tab: General
  hint: 'Free-text notes about the contact for your own reference.'
is_blocked_globally:
  label: 'Caller blocked'
  tab: General
  hint: "When on, all incoming calls from this contact's phone numbers are rejected system-wide."
handling_strategy.type:
  label: 'Incoming call handling'
  tab: General
  hint: 'How incoming calls from this contact are handled. Default means no override. Other options route the call to a specific call flow, extension, user, or SIP device.'
handling_strategy.call_flow_id:
  label: 'Call flow'
  tab: General
  hint: 'The call flow to route calls from this contact to when handling strategy is set to Call flow.'
handling_strategy.extension_id:
  label: Extension
  tab: General
  hint: 'The extension to route calls from this contact to when handling strategy is set to Extension.'
handling_strategy.user_id:
  label: User
  tab: General
  hint: 'The user to route calls from this contact to when handling strategy is set to User.'
handling_strategy.sip_device_id:
  label: 'Phone / SIP device'
  tab: General
  hint: 'The SIP device to route calls from this contact to when handling strategy is set to SIP device.'
```