Lincoln AI

Lincoln AI is the agent behind Dashboard → Conversations. You tell it what you want in plain language and it does the work with your workspace’s own tools: phone numbers, voice agents, campaigns, contacts, automations, knowledge, videos and more. These endpoints let your code (or your own AI agent, over MCP) talk to it directly. Conversations you start here are ordinary Lincoln conversations, so they also appear in the dashboard, and you can pick a thread up from either side.

Endpoint	What it does	Scope
`POST /v1/lincoln/messages`	Send Lincoln a message, or answer its pending approvals	`lincoln:write`
`GET /v1/lincoln/conversations/{id}`	Status, latest reply, actions, pending approvals and the transcript	`lincoln:read`
`GET /v1/lincoln/conversations`	Every conversation in the workspace, newest first	`lincoln:read`

Lincoln AI must be on the workspace’s plan (it comes with the Growth Marketing Manager). Through the API, each message is billed from your prepaid balance at the AI model cost of the turn plus a 20% markup (Lincoln in the dashboard stays free). It shows up as ai_agent in GET /v1/billing/events, and a request returns 402 payment_required when the balance is empty and auto-refill is off. The actions Lincoln takes are billed on top, exactly as they are in the dashboard, and anything that costs money waits for your approval first.

1. Give Lincoln a task

Leave out conversation_id to start a new conversation.

curl -X POST "https://api.lumisreach.com/api/v1/lincoln/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Which of my phone numbers got the most calls this week?" }'

The request waits for Lincoln to finish (up to wait_seconds, default 120, max 240):

{
  "data": {
    "conversation_id": "9b0e4c1a-…",
    "title": "Which of my phone numbers got the most calls this week?",
    "status": "idle",
    "run_id": "wrun_…",
    "reply": "Your main line, +1 415 555 0123, took 42 calls this week, more than your other two combined.",
    "actions": [
      {
        "tool_call_id": "toolu_…",
        "tool": "list_phone_numbers",
        "status": "completed",
        "input": {},
        "output": { "numbers": [ … ] },
        "error": null
      }
    ],
    "pending_approvals": [],
    "error": null,
    "updated_at": "2026-09-26T18:04:12.102Z"
  }
}

Send the next message with the same conversation_id to follow up. Lincoln remembers the whole thread.

2. Long tasks: poll

If Lincoln is still working when wait_seconds runs out (or you passed "wait_seconds": 0), status is working. The task keeps running; poll until it settles:

curl "https://api.lumisreach.com/api/v1/lincoln/conversations/9b0e4c1a-…" \
  -H "Authorization: Bearer YOUR_API_KEY"

While it works, reply holds what Lincoln has said so far. A conversation takes one message at a time: sending another while it is working returns 409 conflict.

`status`	Meaning
`working`	Lincoln is mid-task. Poll again in a few seconds.
`idle`	Done. `reply` is final; send your next message whenever you like.
`awaiting_approval`	Paused on something that costs money or can’t be undone. See below.
`failed`	The task errored; `error` says why. You can send another message.

3. Approvals

Before anything that spends money or can’t be undone (buying a number, placing a call, sending texts, publishing a video), Lincoln stops and asks. The response comes back as awaiting_approval:

{
  "data": {
    "status": "awaiting_approval",
    "reply": "I found +1 415 555 0188. Want me to buy it?",
    "pending_approvals": [
      {
        "approval_id": "approval-toolu_…",
        "tool_call_id": "toolu_…",
        "tool": "buy_phone_number",
        "input": { "phoneNumber": "+14155550188" },
        "reason": "Buying a number charges the card on file $5.00 per number, every month."
      }
    ]
  }
}

Answer every pending approval in one request, with approvals instead of message:

curl -X POST "https://api.lumisreach.com/api/v1/lincoln/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "9b0e4c1a-…",
    "approvals": [{ "approval_id": "approval-toolu_…", "approved": true }]
  }'

Lincoln carries on from where it stopped. Declining ("approved": false, optionally with a reason) tells Lincoln not to do it, and it replies accordingly. A new message is refused with 409 conflict until the pending approvals are answered.

Over MCP

The same three operations are MCP tools on the LumisReach MCP server: ask_lincoln, get_lincoln_conversation and list_lincoln_conversations. ask_lincoln waits 45 seconds by default (so it fits inside most MCP clients’ tool timeout) and returns working for longer tasks, which your agent then follows with get_lincoln_conversation.

Getting Started

Concepts

Quick Agent Actions

Videos

Video Schedules

Calls, Texts and Contacts

Account

Sub-entities

Billing

Phone Numbers

Number Configuration

Caller IDs

Enterprise Registration

Enterprise Registration (Legacy)

Branded Calling

Dialer Calls

Call Webhooks

Inbound SMS

SMS

WebRTC

Documents

Reputation

Usage

Lincoln AI

1. Give Lincoln a task

2. Long tasks: poll

3. Approvals

Over MCP

​1. Give Lincoln a task

​2. Long tasks: poll

​3. Approvals

​Over MCP

1. Give Lincoln a task

2. Long tasks: poll

3. Approvals

Over MCP