Channel Hub

Directory sync & project users API

Admin endpoints for customer directories, CRM/spreadsheet sync, bulk delete, and runtime identity linking.

Service routing#

Customer directory admin is split across two backend services. The UI routes through the same gateway paths your integrations should use.

Service	Gateway base	Responsibility
directory-sync-service	https://api.viksaai.com/directory-sync	Schema, customer CRUD, CSV import/export, bulk delete, data sources, SCIM, CRM/sheet sync
volt-engine-service	https://api.viksaai.com/volt-engine	Runtime identity link/unlink, unmatched users, invoker audit (webhook hot path)

Scope payload#

Required on every requestjson

{
  "account_id": "acc_…",
  "org_id": "org_…",
  "project_id": "prj_…"
}

Project users (directory-sync-service)#

Base path: https://api.viksaai.com/directory-sync/internal/volt/project-users. See also Subject binding & project users for the product workflow.

Endpoint	Permission	Description
`https://api.viksaai.com/directory-sync/internal/volt/project-users/schema/get`	view	Load project user schema (primary key, fields, connector bindings, match messages).
`https://api.viksaai.com/directory-sync/internal/volt/project-users/schema/upsert`	update	Create or replace schema definition and auto-match rules.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/list`	view	Paginated customer index. Optional filters: search, enabled_only, data_source_kind, data_source_provider, data_source_connection_id.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/get`	view	Full customer record — profile, data_source, connector status, identity links, grants.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/upsert`	update	Create or update a customer row (syncs connector primary keys from profile fields).
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/delete`	delete	Delete one customer by customer_user_id; revokes grants and identity links.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/delete-bulk`	delete	Start async purge for up to 500 customers by customer_user_ids. Returns purge_id immediately; poll /users/purge/get for progress.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/delete-preview`	view	Count customers matching search or data-source filters before bulk delete (requires restrictive filters).
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/delete-by-filter`	delete	Start async purge for customers matching filters (max 5000). Deleting all customers requires confirm_project_id matching project_id. Poll /users/purge/get for progress.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/purge/get`	view	Get async customer purge status by purge_id (progress_pct, stats, errors_sample).
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/purge/list`	view	List customer purge runs for the project; active_only returns pending/running jobs.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/data-sources/list`	view	Summarize customer counts grouped by data source (manual, csv, scim, directory_sync).
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/import-csv`	execute	Bulk upsert from CSV text. Sets data_source metadata (kind csv, provider csv_file by default).
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/export-csv`	view	Export customer rows as CSV (optional search filter).
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/attach-channel-grant`	update	Link customer to channel access grant and assign agents.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/channel-access/list`	view	Per-connector access rows for a customer (grant status, linked identity).
`https://api.viksaai.com/directory-sync/internal/volt/project-users/users/set-connector-enabled`	update	Enable or disable one connector for a customer without deleting the row.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/scim/enable`	update	Enable enterprise SCIM provisioning for the project user directory.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/scim/disable`	delete	Disable SCIM provisioning.
`https://api.viksaai.com/directory-sync/internal/volt/project-users/scim/status`	view	SCIM endpoint URL and token metadata for IdP configuration.

List & delete filters#

POST /users/list, /users/delete-preview, and /users/delete-by-filter accept the same optional filters:

search — substring match on primary key and profile fields
enabled_only — only enabled customers
data_source_kind — manual, csv, scim, or directory_sync
data_source_provider — e.g. csv_file, hubspot
data_source_connection_id — sync connection id for directory_sync rows

users/list with data source filterjson

{
  "account_id": "acc_…",
  "org_id": "org_…",
  "project_id": "prj_…",
  "search": "alice",
  "page": 1,
  "page_size": 25,
  "enabled_only": false,
  "data_source_kind": "directory_sync",
  "data_source_provider": "hubspot",
  "data_source_connection_id": "dconn_…"
}

Data source kinds#

Each customer row stores a data_source object. The Channel Hub Customers tab shows this in the Data source column; /users/data-sources/list returns aggregated counts for filters and bulk delete by source.

kind	Meaning
manual	Created in UI or API without an import/sync tag.
csv	CSV import (users/import-csv or mapped import).
scim	Enterprise IdP SCIM provisioning.
directory_sync	CRM or spreadsheet sync connection.

Directory sync connections (directory-sync-service)#

Base path: https://api.viksaai.com/directory-sync/internal/volt/directory-sync. Configure connections in Channel Hub → Data sources.

Endpoint	Permission	Description
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/providers/list`	view	Catalog of supported sync providers (HubSpot, Google Sheets, etc.).
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/connections/list`	view	Saved sync connections for the project.
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/connections/get`	view	Load one connection by connection_id.
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/connections/upsert`	update	Create or update a provider connection (credentials, field mapping).
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/connections/delete`	delete	Remove a sync connection.
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/connections/test`	execute	Validate credentials and mapping without writing customers.
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/connections/preview`	view	Sample rows from the remote source using current field mapping.
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/connections/sync`	execute	Run a sync job — upserts customers and tags rows with directory_sync data_source.
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/runs/list`	view	Paginated sync run history.
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/runs/get`	view	Single sync run status, counts, and errors.
`https://api.viksaai.com/directory-sync/internal/volt/directory-sync/import/csv-mapped`	execute	Import CSV with explicit column → schema field mapping (used by mapped import UI).

Runtime identity (volt-engine-service)#

Identity linking stays on volt-engine because webhooks resolve users on the runtime hot path. Manage links from the customer detail drawer or the Unmatched tab.

Endpoint	Permission	Description
`https://api.viksaai.com/volt-engine/internal/volt/project-users/identities/link`	update	Manually bind connector external_user_id → customer_user_id.
`https://api.viksaai.com/volt-engine/internal/volt/project-users/identities/unlink`	delete	Revoke grant and remove connector link.
`https://api.viksaai.com/volt-engine/internal/volt/project-users/identities/list`	view	Identity links for one customer_user_id.
`https://api.viksaai.com/volt-engine/internal/volt/project-users/identities/list-all`	view	Paginated list of all connector → customer links (used from customer detail).
`https://api.viksaai.com/volt-engine/internal/volt/project-users/unmatched/list`	view	Connector directory users seen on webhooks with no project_user_identities link.
`https://api.viksaai.com/volt-engine/internal/volt/project-users/audit/list`	view	Platform-injected invoker fields per agent dispatch.