External Data API

Read-only REST API for pulling leads, conversations, tickets, visitors, and analytics into your CRM or internal systems.

Overview

The External Data API lets you pull your organization's data — leads, conversations, tickets, visitors, and analytics — into your own CRM or internal systems. Data retrieval endpoints are read-only (GET). Management endpoints (e.g. webhooks) support POST/DELETE. All endpoints are authenticated via secret API keys and scoped to your organization.

Plan requirements: Pro plan and above for REST API access. Enterprise plan for Webhooks. Free plan organizations cannot use this API.

Authentication

Create a Data API key from Settings → API Keys in your dashboard. Select data as the scope. The key will have a sk_live_ prefix.

Pass the key in the X-Api-Key header or as a Bearer token:

Authenticationbash

# Option 1: X-Api-Key header
curl -H "X-Api-Key: sk_live_YOUR_KEY" https://api.nextcap.ai/api/v1/external/leads

# Option 2: Authorization Bearer
curl -H "Authorization: Bearer sk_live_YOUR_KEY" https://api.nextcap.ai/api/v1/external/leads

This API is server-to-server only. Requests from browsers (with an Origin header) are blocked with 403. Never expose your sk_live_ key in frontend code.

Pagination & Filtering

All list endpoints support pagination and date filtering:

pageinteger

Page number (default: 1).

per_pageinteger

Items per page, 1–100 (default: 20).

created_afterISO 8601

Filter items created after this date.

created_beforeISO 8601

Filter items created before this date.

Response envelopejson

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}

Rate Limits

Each API key has a per-minute rate limit (default: 60 rpm). Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceeding the limit returns 429 Too Many Requests.

Leads

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  "https://api.nextcap.ai/api/v1/external/leads?per_page=10&created_after=2026-01-01"

GET/external/leadsAPI Key

List all leads for your organization.

sourcestring

Filter by source: pre_chat_form, in_chat, manual, telegram.

agent_idUUID

Filter by widget/agent ID.

emailstring

Search by email (partial match).

Response — 200 OKjson

{
  "data": [
    {
      "id": "uuid",
      "email": "john@acme.com",
      "name": "John Doe",
      "phone": "+1-555-0100",
      "company": "Acme Inc",
      "custom_fields": {},
      "source": "pre_chat_form",
      "agent_id": "uuid",
      "conversation_id": "uuid",
      "visitor_id": "uuid",
      "created_at": "2026-03-15T10:30:00.000Z",
      "updated_at": "2026-03-15T10:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}

GET/external/leads/:idAPI Key

Get a single lead by ID.

Conversations

GET/external/conversationsAPI Key

List conversations.

statusstring

Filter: active, handed_off, ticketed, resolved, archived.

agent_idUUID

Filter by widget/agent ID.

visitor_idstring

Filter by visitor text ID.

assigned_agent_idUUID

Filter by assigned human agent.

GET/external/conversations/:idAPI Key

Get a single conversation.

GET/external/conversations/:id/messagesAPI Key

List messages in a conversation.

Response — 200 OKjson

{
  "data": [
    {
      "id": "uuid",
      "conversation_id": "uuid",
      "role": "user",
      "content": "How do I reset my password?",
      "sources": null,
      "attachments": null,
      "feedback": null,
      "created_at": "2026-03-15T10:30:00.000Z"
    },
    {
      "id": "uuid",
      "conversation_id": "uuid",
      "role": "assistant",
      "content": "You can reset your password from...",
      "sources": [{ "title": "Password Reset Guide", "chunk": "To reset..." }],
      "attachments": null,
      "feedback": "positive",
      "created_at": "2026-03-15T10:30:05.000Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 8, "total_pages": 1 }
}

Messages are returned in chronological order. The role field can be user, assistant, system, or agent (human agent messages during handoff). The sources field contains knowledge base citations. Token counts, latency, and model information are not exposed.

Tickets

GET/external/ticketsAPI Key

List support tickets.

statusstring

Filter: new, open, in_progress, waiting_customer, waiting_internal, resolved, closed, reopened.

prioritystring

Filter: low, normal, high, urgent.

department_idUUID

Filter by department.

assigned_agent_idUUID

Filter by assigned agent.

categorystring

Filter by category.

tagsstring

Comma-separated tag filter.

sourcestring

Filter by source: handoff, widget, dashboard, email, api, import, telegram.

GET/external/tickets/:idAPI Key

Get a single ticket with full details.

GET/external/tickets/:id/eventsAPI Key

Get the ticket timeline (status changes, assignments, replies).

Internal notes added by agents are never included in this response.

Visitors

GET/external/visitorsAPI Key

List tracked visitors.

countrystring

Filter by ISO country code (e.g., US, DE).

has_emailboolean

Filter by whether the visitor has a captured email.

GET/external/visitors/:idAPI Key

Get a single visitor profile.

GET/external/visitors/:id/sessionsAPI Key

List visit sessions (UTM data, referrer, page views).

GET/external/visitors/:id/profileAPI Key

Get the AI-generated visitor profile (sentiment, topics, interests).

Departments

GET/external/departmentsAPI Key

List all active departments.

GET/external/departments/:idAPI Key

Get a single department.

Analytics

GET/external/analytics/overviewAPI Key

Aggregated metrics for a date range.

start_dateYYYY-MM-DDrequired

Start of the date range.

end_dateYYYY-MM-DDrequired

End of the date range.

GET/external/analytics/dailyAPI Key

Daily breakdown of metrics for the date range.

start_dateYYYY-MM-DDrequired

Start of the date range.

end_dateYYYY-MM-DDrequired

End of the date range.