KDesk Contact Integration

Contact Sync connects KDesk to your identity directory so your Contacts list stays up to date automatically. Each “connection” is an inbound directory pull that imports people into KDesk as contacts, using a mapping you control. You can create multiple connections for the same team to handle different business units, domains, or scoping rules, and you can run them individually or all at once.

Contact Sync only pulls data into KDesk. It is designed to keep your contact directory consistent across ticketing, notifications, and the contact portal.

How to Access Contact Sync

In the KDesk App, open the Team menu and select Contact Sync. If you do not see it, your team may not have contact sync enabled, or your membership may not have permission to manage integrations.

What a Connection Includes

Each connection has a provider (Google Workspace or Microsoft Entra), an enabled/paused state, a scoping rule (“Authorized groups”), and a field mapping that translates directory attributes into KDesk contact fields. Provider credentials are stored securely; when editing an existing connection you can usually leave secret fields blank to keep the current secret/key, or paste a new value to rotate it.

Connection area	What it controls
Initial	Name, description, notes, provider selection, and whether the connection is enabled.
Mapping	How directory fields populate KDesk contact fields, including static values.
Authorized groups	Scoping rules that limit which directory entries are imported.
Provider settings	Credentials and provider-specific configuration for Google Workspace or Microsoft Entra.

Creating a New Connection

From the Contact Sync page, choose New connection and select your provider. Add a name that describes the scope (for example, a region, OU, or department). Leave the connection enabled if you want it to be eligible to run immediately, then complete “Authorized groups” and “Mapping” before saving.

After saving, the connection appears in the directory connections list with its status and last/next run indicators. Use Run to execute a single connection, or Run all to execute every enabled connection for the team.

Running Sync and Reviewing Results

Each connection card includes a Logs action that shows recent sync outcomes. Logs are the primary place to confirm that the connection is pulling the expected users, applying scoping rules correctly, and mapping fields as intended. If something looks off, adjust the authorized groups rule or mapping and run the connection again.

Authorized Groups (Scoping)

Authorized Groups limits which directory users are eligible for import. This is useful when your directory contains users who should not be added as support contacts, or when you want separate connections for different departments or OUs.

Mode	How it works	When to use it
Any (values list)	You provide a comma-separated list of group names that are allowed.	Best when you have a small, stable set of groups such as “Customers”, “VIP”, or “Managed Services”.
Regex (attribute + pattern)	You provide an attribute name and a regex pattern. The connection imports entries whose attribute matches.	Best for OU-based scoping (commonly used with Google Workspace) or other consistent directory attributes.

For regex-based scoping, the attribute is typically something like ou, and the pattern can match a full OU path or a subset of organizational structure. This approach is also useful when you need multiple connections that target different scopes within the same team.

Mapping (Directory Field → KDesk Contact Field)

Mapping defines how data from the directory becomes fields on the KDesk contact record. Sources support dotted paths and array indices (for example, organizations[0].department). Targets are KDesk contact fields such as name, company, job title, division, and notification/portal permissions.

Email and phone targets support labeled entries (for example, “work” or “mobile”), which becomes part of how the contact stores multiple addresses and numbers. Static values are supported when you want a constant value applied to all imported contacts for that connection.

Mapping feature	What it does	Example
Source path	Selects the directory attribute to read.	name.givenName, primaryEmail, organizations[0].title
KDesk target field	Selects which contact field is written in KDesk.	firstName, lastName, job, division
Email/Phone label	Stores the value under a label inside Emails/Phones.	Target: Email with label work (stored like emails.work)
Static value	Writes the same value for every imported contact.	Set canAccessWebPortal to true for all contacts in a “Customers” scope

Boolean targets (such as portal access and notification toggles) should map to boolean-like values (for example, true / false). Use static values when your directory does not have a clean attribute for these settings.

Example Mapping JSON

This example maps common Google-style fields into KDesk and stores the primary email under the “work” label.

{ "name.givenName": "firstName", "name.familyName": "lastName", "primaryEmail": "emails.work", "organizations[0].title": "job", "organizations[0].department": "division", "const:true": "contactIsActive", "const:true": "canAccessWebPortal", "const:true": "emailTicketUpdates" }

Use mapping to control exactly which fields KDesk manages from the directory. Directory identifiers are tracked under “Directory / Sync” inside the contact editor and are treated as sync metadata rather than day-to-day profile fields.

Provider Settings: Google Workspace

Google Workspace connections use a service account with domain-wide delegation. You provide an admin email (used for delegated access), a customer identifier (commonly my_customer), and the service account JSON. The optional “Fetch groups” setting allows the connection to pull directory groups to support group-based scoping and organization-aware imports.

Field	What to enter
Admin email	A Workspace admin email used for delegated access (for example admin@company.com).
Customer	Your customer identifier (commonly my_customer).
Service account JSON	The full JSON key payload for your service account (domain-wide delegation enabled).
Fetch groups	Enable when you need group-aware scoping and group pulling as part of the import.

Provider Settings: Microsoft Entra

Microsoft Entra connections use tenant and app registration credentials. You provide your Tenant ID, Client ID, and Client Secret, plus the directory scopes the connection should use. Scopes are entered as a comma-separated list and control what the connection is allowed to read from Entra during the directory pull.

Field	What to enter
Tenant ID	Your Entra tenant (directory) ID.
Client ID	The Application (client) ID for your Entra app registration.
Client Secret	A valid secret value for the app registration (used for client credential access).
Directory scopes	Comma-separated scopes (default shown as User.Read.All in KDesk).

How Contact Sync Integrates Across KDesk

Once contacts are synced into KDesk, they appear in the Contacts directory, can be searched and referenced from tickets, and can be used for portal access and notification rules depending on how you mapped those fields. If your mapping enables portal access and your team has the portal enabled in Team Settings, the contact can sign in via the contact portal flow. If your mapping enables email notification toggles, KDesk can include the contact in email updates according to your team’s communication settings and the contact’s preferences.