CRM Team Directory

List, search, and look up the employees (seats) in your Next Cap organization from your CRM. Owner / admin only.

Overview

The CRM Team Directory API lets you list, search, and look up the employees (team members / seats) in your Next Cap organization from your own CRM or internal tools. Use it to reconcile users between systems, show a picker of Next Cap agents inside your CRM UI, or audit seat usage.

Owners and admins only. All Team Directory endpoints require the team:invite permission, which in the default role map is restricted to owner and admin seats. Regular members, viewers, and channel-specific roles (live-chat agent, ticketing agent, etc.) receive 403 Forbidden.

Authentication

Same as every other CRM API endpoint — a CRM key with the nextcap_ck_ prefix. Server-to-server only. See the CRM Integration page for how to obtain a key.

HTTP Headerbash

X-Api-Key: nextcap_ck_YOUR_KEY

# or

Authorization: Bearer nextcap_ck_YOUR_KEY

Response Shape

Every member endpoint returns the same employee object. Sensitive fields (password hashes, OAuth identifiers, one-time-password flags) are never included.

Employee objectjson

{
  "id": "b1a2c3d4-5678-90ab-cdef-112233445566",
  "email": "alice@acme.com",
  "name": "Alice Chen",
  "chat_display_name": "Alice",
  "phone": "+1-555-0101",
  "avatar_url": "https://...",
  "role": "admin",
  "role_id": "ddd...",
  "role_name": "Support Admin",
  "role_slug": "support-admin",
  "role_color": "#f97316",
  "role_is_system": false,
  "seat_type": "full",
  "email_verified": true,
  "availability_status": "online",
  "current_activity": "Viewing tickets",
  "spoken_languages": ["en", "fa"],
  "last_active_at": "2026-04-19T14:05:11.000Z",
  "last_login_at":  "2026-04-19T09:12:44.000Z",
  "disabled_at": null,
  "created_at": "2025-11-02T08:00:00.000Z",
  "updated_at": "2026-04-19T14:05:11.000Z"
}

Quick Start

curl "https://api.nextcap.ai/api/v1/external/crm/members?page=1&per_page=50" \
  -H "X-Api-Key: nextcap_ck_YOUR_KEY"

Endpoints

GET/external/crm/membersCRM Key

List all employees in the calling organization. Soft-deleted users are excluded by default; disabled users are excluded unless include_disabled=true.

pageinteger

Page number, 1-indexed. Default: 1.

per_pageinteger

Results per page, 1–100. Default: 20.

searchstring

Case-insensitive substring match on email and name.

rolestring

Filter by legacy role: owner, admin, member, viewer.

seat_typestring

full (dashboard seat) or api_only (CRM-only seat).

availability_statusstring

online, away, busy, or offline.

include_disabledboolean

Include disabled accounts in the result (default: false).

sort_bystring

createdAt, lastActiveAt, lastLoginAt, name, or email. Default: createdAt.

sort_orderstring

asc or desc. Default: desc.

GET/external/crm/members/:idCRM Key

Fetch a single employee by their Next Cap user ID. Returns 404 if the ID does not belong to your organization or the user has been removed.

GET/external/crm/members/by-email/:emailCRM Key

Lookup an employee by email address. Case-insensitive. Returns 404 if no active user matches.

Emails must be URL-encoded (e.g. @ → %40). Most HTTP clients do this automatically when you pass the email as a path parameter.

Lookup by Email — Example

# Email must be URL-encoded (@ → %40)
curl "https://api.nextcap.ai/api/v1/external/crm/members/by-email/alice%40acme.com" \
  -H "X-Api-Key: nextcap_ck_YOUR_KEY"

Pagination Envelope

The GET /members list endpoint returns a standard envelope. Single-record endpoints return only data.

List responsejson

{
  "data": [ /* employee objects */ ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 137,
    "total_pages": 3
  }
}

Permissions Reference

Team Directory Permissions

GET /membersteam:invite

List employees. Owners and admins in the default role map.

GET /members/:idteam:invite

Fetch a single employee by ID.

GET /members/by-email/:emailteam:invite

Fetch a single employee by email.

If you need a seat without team:invite to read the directory (e.g. a reporting-only integration), create a custom role that includes team:invite in Settings → Roles and assign it to the CRM seat. Granting team:invite also lets that seat invite new members — scope it accordingly.