Developers › Start
Developer Reference Quickstart Mint a key, submit one session, and watch it reach a terminal state. The API is small and asynchronous: you notify LeadLogiX that a conversation is ready, then poll until it is done. Everything below can be run against the sandbox, where nothing touches production leads or reporting.
What are you building? Pick the job. Each row is a complete path, in order. Your job The path What you need Get conversations scored The starting point for everyone. This page, then Ingest a session An ingestion key. POST /api/v1/sessions , then poll. Recognise a returning caller mid-conversation Give an agent memory. Recognise a returning customer Your ingestion key on your own workspace; OAuth as an installed app. Read scored leads into an AI agent MCP → Hosted server OAuth token with leads:read . No polling — the model calls tools. Drive LeadLogiX from Claude Desktop or Cursor MCP → leadval-mcp (npm) Your own ingestion key, running locally over stdio. Push leads into your own system Webhooks & polling No webhook signature exists — read that page before designing around one. Send your own fields alongside a conversation Custom metadata , then Tool calls as evidence Nothing extra — it rides on the session you already send. Let other companies connect their LeadLogiX OAuth 2.1 / OIDC , which sets the build order Open registration; no approval step. Add "Sign in with LeadLogiX" to your product Sign in with LeadLogiX OIDC. openid + workspace:read is enough.
What you can build today Before you read further: one path is not self-service yet. Notify and poll score conversations your AI Agents already write to LeadLogiX — POST /api/v1/sessions, then poll the status Identity and profiles recognise a returning caller and follow the pointers, with the same ingestion key (the workspace must have the API enabled) MCP read leads, customer histories, routing and hours into a model — hosted over OAuth, or locally with leadval-mcp OAuth applications apps other customers install, and Sign in with LeadLogiX — open registration, no approval step A custom agent's write path the record contract is published (Session object) but the transport that writes it is not self-service yet; the supported producers are the AI Agents supplied with LeadLogiX. Building your own agent? Contact support@evas.live and it is arranged with you The one thing to understand before anything else LeadLogiX is notify-then-poll , not request-then-response. You do not upload a conversation and get a score back. The conversation is written to LeadLogiX's storage as it happens; you then tell LeadLogiX a session is finished, and it scores it in the background. POST /api/v1/sessions returns 202 Accepted and an id — never a score.
How the pieces fit Four surfaces, and which one answers which question. Surface Direction Credential Answers Ingestion API /api/v1/sessions You → LeadLogiX Ingestion key val_key__… "Score this conversation." Identity API /api/v1/identity/* You → LeadLogiX Ingestion key "Is this the same person?" and "do we know this caller?" Hosted MCP /mcp An AI agent → LeadLogiX OAuth access token "What do we know about this lead or customer?" Delivery CRM sync, webhooks, automations LeadLogiX → you Configured in the workspace "Tell me when something happens."
Which credential Three of them, and they do not overlap. Which credential: your own servers acting on your own workspace use an ingestion key (X-API-Key: val_key__…); a person signed in to LeadLogiX uses a login session token; an application other LeadLogiX customers install uses an OAuth token — with resource=…/mcp to read data through MCP, or openid to sign people in. Credential Who uses it Where it works val_key__… Your servers and AI Agents The /api/v1 and /api/v2 endpoints — ingestion, identity, profiles. It acts on your own workspace and never expires on its own. Login session token A signed-in person, or your app acting as one Workspace and admin endpoints, including /api/tenant/keys/* , and the sandbox handshake OAuth access token An application a customer authorized The MCP endpoint /mcp , scoped to exactly one workspace They are not interchangeable, and a login session is not a service credential Sending an ingestion key to /mcp , or an OAuth token to /api/v1/sessions , fails — and the error says so. A login session token comes from a person signing in, carries an inactivity timeout and is revoked whenever roles or passwords change: a background job built on one works in testing and fails in production, on a schedule nobody controls. Building something other customers install? Do not ask them for an API key — use OAuth .
Send your first session Four steps. The first two need no code. Mint an ingestion key Open Settings → API Playground as a workspace admin and click Generate . The key is shown once. Keys start with val_key__ and authenticate your servers — not your users. Keep it in your backend or secret manager, never in a browser or mobile app; rotating means revoking and re-minting. Send one in the Playground first The Playground submits through the same routes as your code and shows the request, the live status timeline and the conformance notes as they arrive. Getting a session through there first separates "my request is wrong" from "my pipeline is wrong", which is most of the debugging. Find it: Settings > API Playground. sandbox is on by default Notify from your own code One POST, two fields. LeadLogiX reads the conversation from your workspace's raw lead storage, so you never push transcript content through the API. Re-sending the same sessionId is safe — it never re-queues. processor names the line of business — 2 real estate, 3 US life insurance, both on every plan; see Processor modes . curl -X POST https://<your-leadval-host>/api/v1/sessions \ -H "X-API-Key: val_key__…" \ -H "Content-Type: application/json" \ -d '{"sessionId":"conv_9F3A21","processor":2}' # 202 Accepted # {"status":"ACCEPTED","sessionId":"conv_9F3A21","processing":{"state":"QUEUED"}} const BASE = "https://<your-leadval-host>"; const res = await fetch(`${BASE}/api/v1/sessions`, { method: "POST", headers: { "X-API-Key": process.env.LEADVAL_API_KEY, "Content-Type": "application/json" }, body: JSON.stringify({ sessionId: "conv_9F3A21", processor: 2 }), }); console.log(res.status, await res.json()); // 202 { status: "ACCEPTED", … } import os import requests BASE = "https://<your-leadval-host>" HEADERS = {"X-API-Key": os.environ["LEADVAL_API_KEY"]} r = requests.post(f"{BASE}/api/v1/sessions", headers=HEADERS, json={"sessionId": "conv_9F3A21", "processor": 2}, timeout=10) print(r.status_code, r.json()) # 202 {"status": "ACCEPTED", ...} Poll until it is terminal curl https://<your-leadval-host>/api/v1/sessions/conv_9F3A21/status \ -H "X-API-Key: val_key__…" # {"processing":{"state":"PROCESSED"}, # "conformance":{"level":"ACCEPTED_WITH_NOTES","notes":[{"code":"SUMMARY_MISSING", … }]}} const TERMINAL = new Set(["PROCESSED", "DEGRADED", "FAILED"]); for (;;) { const r = await fetch(`${BASE}/api/v1/sessions/conv_9F3A21/status`, { headers: { "X-API-Key": process.env.LEADVAL_API_KEY }, }); if (r.status === 429) { // honour Retry-After, then carry on await new Promise((ok) => setTimeout(ok, Number(r.headers.get("Retry-After") ?? 5) * 1000)); continue; } const doc = await r.json(); if (TERMINAL.has(doc.processing.state)) break; // branch on processing.state, never on conformance await new Promise((ok) => setTimeout(ok, 2000)); } import time TERMINAL = {"PROCESSED", "DEGRADED", "FAILED"} while True: r = requests.get(f"{BASE}/api/v1/sessions/conv_9F3A21/status", headers=HEADERS, timeout=10) if r.status_code == 429: # honour Retry-After, then carry on time.sleep(int(r.headers.get("Retry-After", "5"))) continue r.raise_for_status() doc = r.json() if doc["processing"]["state"] in TERMINAL: # branch on processing.state, never on conformance break time.sleep(2) Terminal means PROCESSED , DEGRADED or FAILED — Session object says what each means. The status document never contains PII, a score or a price, so it is safe to log. Notes are a report on your payload, not a pass/fail: ACCEPTED_WITH_NOTES is the ordinary result for a healthy session. The sandbox is opt-in per request, and needs two credentials Without X-LeadVal-Sandbox: true a test session is a real lead — scored, reported and billed like any other. With the header, you must also send your LeadLogiX login session token as Authorization: Bearer … beside the key, for a person who belongs to the key's workspace; the header alone is refused with 401 UNAUTHENTICATED . Sandbox and live session ids are counted separately.
Where the results come out Notify, poll, and results out: your code notifies POST /api/v1/sessions and receives 202, polls GET /api/v1/sessions/{sessionId}/status until processing.state is terminal, and the scored lead leaves LeadLogiX through CRM sync, automations and scheduled jobs. The result is never in the ingestion API — the status says when a session finished, not what it scored. There is no signed event you can subscribe to. That is deliberate, and Webhooks & polling explains the three routes out and which to pick. To read a scored lead into a model, use MCP → Hosted server .
Base URL and format Item Value Base URL Your LeadLogiX host, e.g. https://app.your-workspace.com Content type application/json , required on POST Errors RFC 9457 application/problem+json — branch on code , never on the message. All of them: Ingestion errors & limits Style Asynchronous — notify, then poll status until terminal SDKs None, by design — generate a client from /openapi.yaml . See AI & tooling
Processor modes Chosen per session, in the notify call. Mode Name Kind What runs Plan 2 REALESTATE Line of business Full pipeline: identity, geocoding, quality scoring, pricing. All plans 3 LIFE_INSURANCE_US Line of business Full pipeline, calibrated for US life insurance. No subject geocoding — a policy has no address. All plans 1 IDENTITY_ONLY Pipeline depth Identity resolution only — no scoring or pricing. Unlimited 0 AUTOMATION_ONLY Pipeline depth Runs your automations only — the engine is skipped. Unlimited Send the line of business the conversation belongs to — a wrong one is priced silently The mode selects which calibration prices the lead and which cohort it is compared against, so a life conversation sent as 2 is priced against the wrong market and nothing in the response says so. Modes 0 and 1 require the Unlimited plan and are refused with PLAN_UPGRADE_REQUIRED , never silently downgraded; the plan gate never stands between you and a line of business. The list of lines of business grows A 422 PROCESSOR_UNSUPPORTED enumerates every mode the server accepts, by number and label — it is generated from LeadLogiX's own registry, so it can never tell you a mode does not exist on the day it starts working. Read that response rather than hard-coding this table, and treat an unfamiliar processorLabel as an unknown line of business — never as real estate.