Intellia
API reference · v1

Build on Intellia

Read conversations and qualified leads into your CRM, chat with your chatbots from WhatsApp or your own app, keep their knowledge in sync with your systems, and get signed webhooks the moment a lead arrives.

Overview

The API is JSON over HTTPS. Every request is made with an organization API key and sees only that organization's data.

Base URL: https://intellia.naidvartechnologies.com/api/v1

curl https://intellia.naidvartechnologies.com/api/v1/leads?status=qualified \
  -H "Authorization: Bearer itl_your_key_here"

Authentication

Create keys in the dashboard under Developers → API keys (Owners and Admins). A key is shown once, when it's created; Intellia stores only a hash of it. Send it as a bearer token — or in an X-Api-Key header:

Authorization: Bearer itl_3f8a...

Each key carries scopes, and each endpoint needs one. Give every integration its own key with only the scopes it uses, and revoke keys you no longer need.

ScopeAllows
bots:readList and read chatbots
chat:writeSend messages to chatbots (a new conversation uses one credit)
conversations:readRead conversations, transcripts and intelligence
leads:readRead leads
leads:writeUpdate a lead's status and notes
insights:readRead insights
knowledge:writeAdd knowledge and list knowledge sources
bookings:readRead appointment bookings
quotes:readRead quotes

Errors & limits

Every error has the same shape:

{
  "error": {
    "code": "validation_failed",
    "message": "The selected status is invalid.",
    "fields": { "status": ["The selected status is invalid."] }
  }
}
CodeStatusMeaning
invalid_api_key401Missing, invalid or revoked key
out_of_credits402No conversation credits left (send message only)
subscription_inactive402Trial or plan has ended (send message only)
insufficient_scope403The key lacks the scope this endpoint needs
not_found404No such resource in your organization
request_failed409e.g. messaging an archived chatbot
validation_failed422Bad parameters — see error.fields
rate_limited429Over 120 requests a minute for this key — honour Retry-After
assistant_unavailable502The AI model didn't answer — safe to retry

Rate limit: 120 requests a minute per key. Over it you get 429 with a Retry-After header (seconds).

Pagination

List endpoints return pages. Pass page (from 1) and, on conversations and leads, per_page (up to 100, default 25). Newest first.

{
  "data": [ ... ],
  "links": { "first": "...?page=1", "last": "...?page=4", "prev": null, "next": "...?page=2" },
  "meta": { "current_page": 1, "last_page": 4, "per_page": 25, "total": 87 }
}

To sync incrementally, filter with updated_since (ISO 8601) and keep the time of your last successful run.

Chatbots

GET/botsbots:read

GET/bots/{id}bots:read

{
  "data": {
    "id": 12, "object": "bot", "name": "Sunny", "status": "active",
    "public_key": "7f549e01-3d49-4ad1-9ddc-f03a80c6f0b1",
    "personality": "friendly", "welcome_message": "Hi! Welcome to Sunny Solar.",
    "lead_capture_enabled": true, "handover_enabled": true,
    "created_at": "2026-09-24T10:02:11+00:00", "updated_at": "2026-09-24T10:05:40+00:00"
  }
}

Send a message

POST/bots/{id}/messageschat:write

Talk to a chatbot from anywhere — a WhatsApp integration, a mobile app, an in-store kiosk. The reply is grounded in the chatbot's knowledge and business profile, and the conversation is analysed, turned into a lead and counted in Insights exactly like a website chat (its channel is api).

FieldDescription
messageRequired. The customer's message (max 4,000 characters).
conversation_idOptional. Continue a conversation this endpoint returned. Omit to start a new one.
contactOptional. { name, email, phone } you already know — saved to the conversation, and a lead is created when there's an email or phone.
curl -X POST https://intellia.naidvartechnologies.com/api/v1/bots/12/messages \
  -H "Authorization: Bearer itl_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Do you install solar in Gweru?",
       "contact": {"name": "Tendai", "phone": "+263 77 123 4567"}}'

{
  "data": {
    "object": "reply",
    "conversation_id": 845,
    "reply": "Yes — we install across the Midlands, including Gweru. ...",
    "created": true
  }
}
Starting a conversation uses one conversation credit; continuing it with conversation_id is free. Replies come from the AI model and usually take a few seconds — allow at least 120 seconds before timing out, and retry a 502.

Conversations

GET/conversationsconversations:read

GET/conversations/{id}conversations:read

Filters: bot_id, status (open, closed), channel (widget, api), has_lead=1, handover=1, since, updated_since. The single-conversation endpoint also returns the transcript in messages. Staff test chats are never included.

{
  "data": {
    "id": 845, "object": "conversation", "bot_id": 12, "channel": "widget", "status": "open",
    "contact": { "name": "Tendai", "email": "[email protected]", "phone": null },
    "intelligence": {
      "intent": "product_pricing",
      "summary": "Wants a solar system for a house in Gweru, budget about $3,000.",
      "topics": ["solar", "quote"], "sentiment": "positive", "customer_stage": "ready_to_buy",
      "lead_score": 85,
      "attributes": { "location": "Gweru", "budget": 3000, "appliances": ["Fridge", "TV"] },
      "analyzed_at": "2026-09-24T13:25:05+00:00"
    },
    "handover_requested_at": null,
    "lead_id": 311,
    "messages": [
      { "id": 9001, "role": "user", "content": "I need solar for my house in Gweru...", "created_at": "..." },
      { "id": 9002, "role": "assistant", "content": "Happy to help! ...", "created_at": "..." }
    ],
    "last_message_at": "2026-09-24T13:24:51+00:00",
    "created_at": "2026-09-24T13:24:40+00:00"
  }
}

intelligence.attributes uses the keys of your business attributes (Attributes page) — numbers and currency as numbers, dates as YYYY-MM-DD, choices exactly as configured.

Leads

GET/leadsleads:read

GET/leads/{id}leads:read

PATCH/leads/{id}leads:write

Filters: status, bot_id, since, updated_since. Statuses: new, contacted, qualified, converted, lost, archived.

{
  "data": {
    "id": 311, "object": "lead", "bot_id": 12, "conversation_id": 845,
    "name": "Tendai", "email": "[email protected]", "phone": null,
    "intent": "product_pricing",
    "summary": "Wants a solar system for a house in Gweru, budget about $3,000.",
    "attributes": { "location": "Gweru", "budget": 3000 },
    "score": 85, "status": "qualified", "notes": null,
    "deal_value": 3000.00, "converted_at": null,
    "qualified_at": "2026-09-24T13:25:05+00:00",
    "created_at": "2026-09-24T13:25:05+00:00", "updated_at": "2026-09-24T13:25:05+00:00"
  }
}

Update status, deal value or notes — for example, once your CRM has called the customer. deal_value is what the customer is worth in your organization's currency: it counts as pipeline until the lead is converted, then as revenue (converted_at is set for you).

curl -X PATCH https://intellia.naidvartechnologies.com/api/v1/leads/311 \
  -H "Authorization: Bearer itl_..." -H "Content-Type: application/json" \
  -d '{"status": "converted", "deal_value": 3250, "notes": "Paid deposit 24 Sep"}'

Bookings

GET/bookingsbookings:read

GET/bookings/{id}bookings:read

Appointments made on your booking page, from the chat widget's Book button, or added by your team. Filters: status (confirmed, completed, no_show, cancelled), from and to (on starts_at), updated_since. Sorted by start time. Times are UTC.

{
  "data": {
    "id": 58, "object": "booking", "service_id": 3, "service_name": "Site survey",
    "lead_id": 311, "conversation_id": 845,
    "customer": { "name": "Tendai", "email": "[email protected]", "phone": "+263 77 111 2222" },
    "notes": null, "status": "confirmed", "source": "widget",
    "starts_at": "2026-09-28T07:30:00+00:00", "ends_at": "2026-09-28T08:30:00+00:00",
    "cancelled_at": null, "created_at": "...", "updated_at": "..."
  }
}

Quotes

GET/quotesquotes:read

GET/quotes/{id}quotes:read

Quotes with their lines and totals — handy for pushing accepted quotes into your accounting system. Filters: status (draft, sent, accepted, declined), lead_id, updated_since. expired is true for a sent quote past its valid_until date; url is the customer's page (null for drafts).

{
  "data": {
    "id": 21, "object": "quote", "number": "Q-0021", "lead_id": 311, "conversation_id": 845,
    "customer": { "name": "Tendai", "email": "[email protected]", "phone": null },
    "status": "accepted", "expired": false, "currency": "USD",
    "items": [
      { "product_id": 4, "description": "5kVA inverter", "quantity": 1, "unit": "each", "unit_price": 1200.0, "line_total": 1200.0 },
      { "product_id": null, "description": "Installation", "quantity": 1, "unit": null, "unit_price": 300.0, "line_total": 300.0 }
    ],
    "subtotal": 1500.0, "discount": 0.0, "tax_rate": 15.0, "tax": 225.0, "total": 1725.0,
    "valid_until": "2026-10-08", "url": "https://intellia.naidvartechnologies.com/quote/...",
    "sent_at": "...", "viewed_at": "...", "accepted_at": "...", "accepted_by": "Tendai Moyo",
    "declined_at": null, "decline_reason": null, "created_at": "...", "updated_at": "..."
  }
}

Insights

GET/insights?days=30insights:read

Aggregates over the last 7, 30 or 90 days: totals (conversations, leads, qualified, converted, handovers, average lead score), revenue (won value and deals, average deal, open pipeline, by chatbot and by intent, in currency), intents with shares, topics, sentiment, per-attribute breakdowns (popular values, or min/max/average/median for numbers), daily volume, and open knowledge_gaps.

Knowledge

POST/knowledgeknowledge:write

GET/knowledge-sourcesknowledge:write

Push text from your own systems — a product catalogue, price list or policy — and your chatbots answer from it. Each call adds a document to a knowledge source named by source (default API), created on first use and attached to the chatbots in bot_ids.

curl -X POST https://intellia.naidvartechnologies.com/api/v1/knowledge \
  -H "Authorization: Bearer itl_..." -H "Content-Type: application/json" \
  -d '{"title": "Inverter price list", "source": "Catalogue", "bot_ids": [12],
       "text": "XR-450 hybrid inverter: $1,200. XR-800: $1,950. Prices include installation in Harare."}'

{ "data": { "object": "knowledge_document", "document_id": 77, "chunks_created": 1,
            "knowledge_source": { "id": 9, "object": "knowledge_source", "name": "Catalogue", "type": "api", ... } } }
Sending text that's already in the same source again is a no-op, so it's safe to re-sync on a schedule. Up to 200,000 characters per call.

Webhooks

Add endpoints under Developers → Webhooks. Intellia POSTs a JSON event to each matching endpoint within about ten seconds of it happening.

EventObjectWhen
conversation.startedconversationA customer started a conversation (website widget, WhatsApp or API)
conversation.analyzedconversationIntent, summary and extracted attributes were updated
handover.requestedconversationA visitor asked to talk to a person
lead.createdleadA new lead was captured
lead.qualifiedleadA lead became qualified
lead.updatedleadA lead's status, deal value or notes changed (data.previous_status included)
booking.createdbookingA customer booked an appointment (booking page, chat widget or your team)
booking.cancelledbookingAn appointment was cancelled (data.cancelled_by: customer or business)
quote.sentquoteA quote was emailed to a customer for the first time
quote.acceptedquoteA customer accepted a quote online (the lead is converted at the quoted total)
quote.declinedquoteA customer declined a quote (decline_reason included)
POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Intellia-Webhooks/1.0
Intellia-Event: lead.created
Intellia-Delivery: 5821
Intellia-Signature: t=1790251505,v1=5f2b8e...

{
  "id": "evt_4471",
  "type": "lead.created",
  "created_at": "2026-09-24T13:25:05+00:00",
  "data": { "object": { "id": 311, "object": "lead", "name": "Tendai", ... } }
}

data.object is exactly what the matching GET endpoint returns (a lead or a conversation). Reply with any 2xx within 10 seconds. Otherwise the delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then marked failed — you can redeliver it from the dashboard. Deliveries can arrive more than once or out of order: use the event id to ignore duplicates.

Endpoints must be public https:// URLs. Use Send test in the dashboard to receive a webhook.test event.

Verifying signatures

Each endpoint has a signing secret (whsec_...). Compute an HMAC-SHA256 of {t}.{raw request body} with the secret, compare it to v1 in constant time, and reject timestamps older than five minutes.

Node.js

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

PHP

function verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $sig);
    if (abs(time() - (int) $sig['t']) > 300) return false;
    return hash_equals(hash_hmac('sha256', $sig['t'].'.'.$rawBody, $secret), $sig['v1']);
}

Python

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    sig = dict(part.split("=", 1) for part in header.split(","))
    if abs(time.time() - int(sig["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{sig['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig["v1"])
Verify against the raw body exactly as received — parsing and re-serialising the JSON changes it.

Building something?

Tell us what you're integrating with — we're happy to help, and to add the endpoint you need.

Talk to us →