CRM Module (ItBuild.CRM)

The CRM module manages user profiles, personal data, external identifiers, and social connections. It serves as the central user database for the ItBuild platform.

Overview

Property	Value
Type	Optional standard module
Port	Internal only (behind AuthProxy)
Database	Separate SQL Server database
Admin panel	`/CrmAdmin/`

Key Capabilities

User Management

User profiles — name, contacts, metadata
External IDs — phone numbers, emails, social accounts (Telegram, Google, Discord, VK, GitHub)
User flags — status bits for permissions and states
Project isolation — users belong to specific projects in multi-tenant setup

Standard Features (February 2026)

Notes — comments, call logs, meeting records attached to users
Tags — color-coded segmentation labels with groups
Audit Log — automatic fire-and-forget action tracking
Addresses — user addresses with types (Home, Work, Shipping, Billing)
Custom Fields — dynamic user attributes (String, Number, Date, Bool, Enum)

See CRM Features for details.

Friends System

Friend connections — bidirectional friend relationships between users
Friend management — add, remove, list friends
Friend flags — custom relationship metadata

External ID Management

Users can have multiple external identifiers (user_exid) linked:

ID Type	Source	Example
Phone	SMS verification	`+1234567890`
Email	Email verification / magic link	`user@example.com`
Telegram	Telegram Login	`123456789`
Google	Google OAuth	`google-sub-id`
Apple	Sign In with Apple	`apple-sub-id`
Microsoft	Microsoft OAuth	`ms-oid`
GitHub	GitHub OAuth	`github-user-id`
Facebook	Facebook OAuth	`fb-user-id`
VK	VK OAuth	`vk-user-id`
Discord	Discord OAuth	`discord-user-id`

`user_exid_flags` (since 2026-05)

Each user_exid row carries a bitmask that distinguishes how the contact came to be:

Bit	Name	When set
`1`	`Verified`	The contact was confirmed end-to-end (OTP, magic link, OAuth handshake completed).
`2`	`ManuallyAdded`	The contact was created by an operator through `/CrmAdmin/ExternalIds` and has not yet been verified.
`4`	`Primary`	Reserved for the user's primary contact of a given type.
`128`	`Deleted`	Soft-delete; the row is kept for audit.

Verified and ManuallyAdded are independent — an operator can pre-create a contact and the user can later verify it, leaving both bits set. AML, KYC, and payout-eligibility checks rely on Verified, never on the mere presence of the row. See docs.authproxy.tech/docs/authentication/verified-contacts.md for the full flag semantics and OAuth verified-email matrix.

API Endpoints

CRM Controller

Endpoint	Method	Description
`get_client`	GET	Get user profile by CRM ID
`update_client`	POST	Update user data
`create_client`	POST	Create new user
`search_clients`	GET	Search users by criteria

Friends Controller

Endpoint	Method	Description
`get_friends`	GET	List user's friends
`add_friend`	POST	Add friend connection
`remove_friend`	POST	Remove friend

Private Controller (`/private/v1/`)

Internal API used by AuthProxy and other modules:

Endpoint	Method	Description
`get_user`	POST	Get user by CRM ID (inter-service)
`create_user`	POST	Create user (called by AuthProxy on first login)
`update_user`	POST	Update user (inter-service)
`find_by_external_id`	GET	Find user by phone/email/social ID

Data Model

Main Entities

CRM stores user profiles, verified external ids, relationships, notes, tags, and audit records. Public documentation describes the entity purpose and admin workflows; exact schema is maintained in the module source and generated delivery artifacts.

Integration

How AuthProxy Uses CRM

When a user authenticates (via any method), AuthProxy:

Checks if the external ID exists in CRM (phone, email, Telegram ID, etc.)
If found — returns the existing crm_id for the session
If not found — creates a new CRM user, links the external ID

This is transparent to the end user — first login automatically creates their CRM profile.

Wallet Provisioning (TrexWallet)

When TrexWallet is part of the deployment, CRM can auto-provision a wallet for each client by calling TrexWallet private/v1/create_wallet. The trigger is controlled by the WalletProvision config setting:

`WalletProvision`	Behavior
`OnPhoneConfirm` (default)	Create the wallet when a phone login id is attached (`ext_id_upsert`), if the client has no wallet yet. This is also the behavior when the key is absent.
`OnRegistration`	Create the wallet as soon as the CRM client record is created (`client_upsert`).
`None`	Never auto-create. Use for CRM-only deployments without TrexWallet, or when wallets are provisioned manually/elsewhere.

The wallet group is taken from TrexDefaultGroup (or the referring agent's tariff group); project from Config.Project. The per-client wallet cap lives on TrexWallet (MaxWalletsPerUser). Provisioning is best-effort: a wallet failure is logged but never blocks registration or phone attachment. CRM has no login endpoint (authentication is AuthProxy's domain), so there is no "on first login" mode here.

How Core Module Uses CRM

The Core module accesses CRM through the shared CRM client instead of querying CRM tables directly.

CRM ID as Universal Identifier

The CRM timetick (CRM ID) is the universal user identifier across all platform modules:

AuthProxy → session contains crm_id
    → X-Crm header sent to all backend modules
        → TrexWallet uses crm_id for wallet ownership
        → Chat uses crm_id for message ownership
        → Core uses crm_id for business logic

Admin Panel

Built-in Razor admin at /CrmAdmin/ (proxied via AuthProxy). Page inventory matches the current ItBuild.CRM Pages/CrmAdmin tree and platform admin docs.

Page	Route	Notes
Index (dashboard)	`/CrmAdmin`	Stats, charts, recent activity
CrmUser	`/CrmAdmin/CrmUser`	User list; filters (e.g. timetick, name, phone, email, flags)
UserDetail	`/CrmAdmin/UserDetail?timetick=`	Dossier / detail view
EditUser	`/CrmAdmin/EditUser?timetick=`	Profile edit form; requires `crm.admin` scope
ExternalIds	`/CrmAdmin/ExternalIds`	External identifiers; `crm.admin` for mutations
Friends	`/CrmAdmin/Friends`	Friend graph; `crm.admin` where applicable
Notes	`/CrmAdmin/Notes`	Notes registry (filters required before list load)
Tags	`/CrmAdmin/Tags`	Tag definitions and assignments
Addresses	`/CrmAdmin/Addresses`	User addresses
CustomFields	`/CrmAdmin/CustomFields`	Dynamic field defs and values
AuditLog	`/CrmAdmin/AuditLog`	`crm_audit` registry (filters required)
ReferralTree	`/CrmAdmin/ReferralTree`	Referral hierarchy
CreateUser	`/CrmAdmin/CreateUser`	Create user; `crm.admin`
MergeUsers	`/CrmAdmin/MergeUsers`	Merge flow; `crm.admin`

Operator help anchor for EditUser + related navigation: CRM admin — operator guide.

Configuration

{
  "Config": {
    "DBConnections": {
      "CrmDB": "Server=...;Database=crm_db;..."
    },
    "TrexDefaultGroup": 1,
    "WalletProvision": "OnPhoneConfirm"
  }
}

Error Codes

CRM-specific errors (via ApiCrmError):

Code	Description
`-11001`	User not found
`-11002`	User already exists
`-11003`	Invalid external ID
`5006`	Note not found
`5007`	Tag not found
`5008`	Tag already assigned
`5009`	Address not found
`5010`	Custom field definition not found
`5011`	Field value invalid (type mismatch)
`4008`	Add chat member: contact already a member
`4009`	Add chat member: not a friend (cannot add)

CRM admin — operator guide — EditUser, UserDetail, ExternalIds, Notes, AuditLog
CRM Features — Notes, Tags, Audit, Addresses, Custom Fields
AuthProxy — Session Management — how sessions link to CRM
Platform Overview — module architecture
Chat Module — uses CRM IDs for messaging

Overview​

Key Capabilities​

User Management​

Standard Features (February 2026)​

Friends System​

External ID Management​

user_exid_flags (since 2026-05)​

API Endpoints​

CRM Controller​

Friends Controller​

Private Controller (/private/v1/)​

Data Model​

Main Entities​

Integration​

How AuthProxy Uses CRM​

Wallet Provisioning (TrexWallet)​

How Core Module Uses CRM​

CRM ID as Universal Identifier​

Admin Panel​

Configuration​

Error Codes​

Related Documentation​