NUWAY API

Leads

A lead is one customer visit (a chat, a presentation or a call), scored by NUWAY for buying intent. These are the same leads you see in the dashboard.

List leads

GET /api/v1/external/leads Offset pagination

Leads with filters and sorting.

Query parameters

Name	Description
`rank` string	`hot`, `interested`, `buy`, `cold`, `unsubscribed`
`search` string	Matches name, email, phone or product
`needs_attention` boolean	`true` for leads waiting on a follow-up
`highlighted_only` boolean	`true` for visits where the customer showed real buying interest
`sort` string	`recent` (default), `intent` (highest buying intent first), `priority`
`limit` integer	1–200, default 50
`offset` integer	Default 0

Example request

curl "https://ai.nuway.co/api/v1/external/leads?rank=hot&sort=intent&limit=10" \
  -H "X-API-KEY: $NUWAY_API_KEY"

// Node.js 18+. Uses top-level await: save as .mjs (or set "type": "module").
const res = await fetch("https://ai.nuway.co/api/v1/external/leads?rank=hot&sort=intent&limit=10", {
  method: "GET",
  headers: {
    "X-API-KEY": process.env.NUWAY_API_KEY
  }
});
const data = await res.json();

import os
import requests
r = requests.get(
    "https://ai.nuway.co/api/v1/external/leads?rank=hot&sort=intent&limit=10",
    headers={"X-API-KEY": os.environ["NUWAY_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
data = r.json()

Response

{
  "items": [
    {
      "lead_id": "e3863d86-da23-4a7e-80de-3d68271e8705",
      "name": "Jane Doe",
      "email": "[email protected]",
      "phone": null,
      "country": "United Kingdom",
      "product_name": "Private Office",
      "rank": "hot",
      "rank_label": "Hot Lead",
      "score": 82,
      "crm_status": "OPEN",
      "session_type": "chat",
      "questions_asked": 6,
      "first_seen": "2026-10-10T14:20:49.625106Z",
      "last_session_at": "2026-10-10T14:20:49.625106Z",
      "last_contacted_at": null,
      "needs_attention": true,
      "attention_reason": "Never contacted since the first session — reach out while interest is fresh.",
      "unsubscribed": false,
      "highlighted": true
    }
  ],
  "total": 37,
  "limit": 10,
  "offset": 0,
  "has_more": true
}

Response fields

Name	Description
`lead_id`	The lead's ID.
`name, email, phone, country`	What the customer shared. Anonymous visits have these empty.
`product_name`	The product the visit was about, if any.
`rank, rank_label`	`hot`, `interested`, `buy` or `cold`.
`score`	Buying intent, 0–100.
`crm_status`	Your pipeline status: `OPEN`, `WON`, `LOST`, `MEETING_SET`.
`session_type`	`chat`, `presenter` (AI presentation) or `call`.
`questions_asked`	Questions the customer asked during the visit.
`first_seen, last_session_at, last_contacted_at`	Timestamps.
`needs_attention, attention_reason`	Whether, and why, the lead is waiting on your team.
`revenue_amount`	Revenue you recorded for the lead.
`unsubscribed`	The customer asked not to be contacted.
`highlighted`	The customer showed real buying interest in this visit.

Get a lead

GET /api/v1/external/leads/{lead_id}

One lead in detail: every field from the list, plus the ones below.

Path parameters

Name	Description
`lead_id` string required	The lead's ID.

Example request

curl "https://ai.nuway.co/api/v1/external/leads/{lead_id}" \
  -H "X-API-KEY: $NUWAY_API_KEY"

// Node.js 18+. Uses top-level await: save as .mjs (or set "type": "module").
const res = await fetch("https://ai.nuway.co/api/v1/external/leads/{lead_id}", {
  method: "GET",
  headers: {
    "X-API-KEY": process.env.NUWAY_API_KEY
  }
});
const data = await res.json();

import os
import requests
r = requests.get(
    "https://ai.nuway.co/api/v1/external/leads/{lead_id}",
    headers={"X-API-KEY": os.environ["NUWAY_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
data = r.json()

Response

Name	Description
`sessions`	The visit, with its products and scoring.
`timeline`	Events in order: the visit, contacts, status changes.
`notes, tasks, contact_logs`	Your team's notes, follow-up tasks and logged contacts.
`contact`	The person behind the lead, with totals across all their visits.

Errors 404 when the lead doesn't exist or isn't yours.