REST API + remote MCP

Build on LeadVouch without rebuilding the dashboard.

Connect software, automations or AI agents to the same clients, numbers, call flows, leads, recordings and reports used by LeadVouch operators. Every machine action uses scoped access, audit logging and explicit safety gates.

Start integrating Browse endpoints

REST base

https://api.leadvouch.com/api/v1/agent

MCP server

https://api.leadvouch.com/mcp

Authentication

Bearer agent token

Quick start

Make your first authenticated request

An agency owner creates the token once. Your application stores it as a secret and sends it with every REST request or MCP connection.

1
Create a token
Sign in, open Settings → API tokens, select a profile and copy the token when it is shown.
2
Store it securely
Use LEADVOUCH_AGENT_TOKEN in a secret manager or private environment file. Never put it in model instructions.
3
Discover access
Call /capabilities first. Its response lists the exact operations, client scope and safety permissions available.

First requestLeadVouch

curl https://api.leadvouch.com/api/v1/agent/clients \
  -H "Authorization: Bearer $LEADVOUCH_AGENT_TOKEN"

ProfileBest forAccess

Read only

Reporting and analysis agents

Calls, leads, recordings, reports, audit and exports

Operator

Rank-and-rent and operations agents

Read access plus clients, numbers, campaigns, call flows, DNI and lead triage

Administrator

Trusted agency administration

Operator access plus agency settings, users and billing inputs

Architecture

One platform, two machine interfaces

REST and MCP both execute the same validation, tenant scoping and business rules as the human dashboard. Choose the interface that fits your client; the underlying behavior does not change.

REST API

https://api.leadvouch.com/api/v1/agent

Best for application backends, scripts, Zapier-style integrations and deterministic workflows. Large CSV exports and recording streams stay here.

Remote MCP

https://api.leadvouch.com/mcp

Best for Claude, Claude Code, Hermes, OpenAI and other MCP-capable agents. The agent discovers tools and acts through a standard Streamable HTTP connection.

1. Bearer token

2. Tenant scope

3. Policy gate

4. Dashboard logic

5. Audit event

Agent connection

Connect any remote-MCP client

Add the LeadVouch server URL and bearer header to your agent. The exact configuration file varies by product, but the connection values remain the same.

Generic MCP configurationLeadVouch

{
  "mcpServers": {
    "leadvouch": {
      "type": "http",
      "url": "https://api.leadvouch.com/mcp",
      "headers": {
        "Authorization": "Bearer ${LEADVOUCH_AGENT_TOKEN}"
      }
    }
  }
}

describe_leadvouch

Returns the token policy, endpoint catalog and complete rank-and-rent setup recipe.

leadvouch_read

Runs documented GET operations for calls, leads, reports, clients and configuration.

leadvouch_write

Runs POST, PATCH, PUT and DELETE operations with a required idempotency key.

Safety model

Autonomy is granted in layers

A broad profile does not automatically authorize spending, data deletion or provider calls. Those action classes have independent token switches and are enforced on every request.

Client scope

Pin a token to one client or permit agency-wide access.

Capability profile

Read only, operator and administrator profiles control feature access.

Sensitive actions

External calls, purchases and destructive actions are off by default.

Idempotency

Every mutation needs a stable Idempotency-Key so retries do not repeat work.

Plan capacity

Client creation and number provisioning follow the same approved plan limits as the dashboard.

Idempotent mutationLeadVouch

curl https://api.leadvouch.com/api/v1/agent/clients \
  -X POST \
  -H "Authorization: Bearer $LEADVOUCH_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fairfield-site-v1" \
  -d '{
    "name": "Fairfield Trenchless",
    "industry": "plumbing",
    "timezone": "America/New_York"
  }'

Machine-readable errorLeadVouch

{
  "error": {
    "code": "forbidden",
    "message": "This token is not allowed to make purchases."
  }
}

Reusing the same idempotency key with identical data returns the saved response. Reusing it with different data returns a conflict instead of guessing which action you intended.

Core workflow

Launch a tracked rank-and-rent website

The capability response includes this sequence as structured data, so an agent can discover and execute it without reading the React dashboard.

01
Create client
Creates the website/business container and returns its public DNI siteKey.
02
Add destination
Stores the real phone number that should receive forwarded leads.
03
Create campaign
Labels the channel and source used for attribution and reporting.
04
Create call flow
Defines business hours, whisper behavior, routing targets and fallbacks.
05
Import or purchase
Adopts an existing Twilio/Telnyx number or buys an approved candidate.
06
Assign and verify
Links the number, campaign and call flow; optionally adds a DNI pool and snippet.

Final acceptance remains human.

API success proves configuration. Before publishing a new tracking number, place one controlled call to confirm ringing, whisper, consent disclosure, voicemail and recording audio.

REST reference

Dashboard business operations

Paths below are relative to the REST base URL. The public OpenAPI contract is the machine-readable source of truth.

Open OpenAPI JSON

Discovery

Check a token and discover its exact permissions and tools.

GET/health

Check agent authentication and scope

GET/capabilities

List token-specific operations and workflows

GET/openapi.json

Read the public OpenAPI 3.1 contract

Clients, locations and users

Set up the business or website that owns calls, leads and routing.

GET/clients

List clients

POST/clients

Create a client

GET/clients/{clientId}

Get a client

PATCH/clients/{clientId}

Update a client

GET/clients/{clientId}/destination-numbers

List forwarding destinations

POST/clients/{clientId}/destination-numbers

Create a forwarding destination

DELETE/clients/{clientId}/destination-numbers/{destinationId}

Delete a forwarding destinationDestructive

GET/clients/{clientId}/locations

List locations

POST/clients/{clientId}/locations

Create a location

GET/agency

Read agency settings

PATCH/agency

Update agency settings

GET/users

List dashboard users

POST/users/invite

Invite a dashboard userExternal

DELETE/users/{userId}

Remove a dashboard userDestructive

Providers and tracking numbers

Connect Twilio or Telnyx, adopt numbers, buy numbers and control routing state.

GET/provider-accounts

List provider accounts

POST/provider-accounts

Connect a provider accountExternal

POST/provider-accounts/{id}/health

Check provider connectivityExternal

DELETE/provider-accounts/{id}

Remove a provider accountExternalDestructive

GET/phone-numbers

List tracking numbers

GET/phone-numbers/{id}

Get a tracking number

GET/phone-numbers/importable

List numbers already owned at a providerExternal

POST/phone-numbers/search

Search provider inventoryExternal

POST/phone-numbers/purchase

Purchase a tracking numberExternalPurchase

POST/phone-numbers/import

Import already-owned numbersExternal

PATCH/phone-numbers/{id}/assign

Assign and route a number

POST/phone-numbers/{id}/pause

Pause a numberExternal

POST/phone-numbers/{id}/resume

Resume a numberExternal

POST/phone-numbers/{id}/release

Release a provider numberExternalDestructive

POST/phone-numbers/{id}/reconfigure

Repair provider webhooksExternal

Campaigns and call flows

Describe the source of each lead and decide where every call goes.

GET/campaigns

List campaigns

POST/campaigns

Create a campaign

PATCH/campaigns/{id}

Update a campaign

DELETE/campaigns/{id}

Delete a campaignDestructive

GET/campaigns/{id}/spend

List monthly campaign spend

PUT/campaigns/{id}/spend

Set monthly campaign spend

GET/call-flows

List call flows

POST/call-flows

Create a call flow

GET/call-flows/{id}

Get a call flow

PATCH/call-flows/{id}

Update a call flow

DELETE/call-flows/{id}

Delete a call flowDestructive

POST/call-flows/{id}/duplicate

Duplicate a call flow

Website tracking (DNI)

Swap website phone numbers per visitor session for source-level attribution.

GET/dni/verify

Verify a DNI installation

GET/dni/snippet.js

Download the website snippetREST only

GET/dni/pools

List number pools

POST/dni/pools

Create a number pool

PATCH/dni/pools/{id}

Update a number pool

DELETE/dni/pools/{id}

Archive a number poolDestructive

POST/dni/pools/estimate

Estimate the required pool size

Calls and recordings

Read call activity, inspect outcomes and retrieve authorized recordings.

GET/calls

List and filter calls

GET/calls/{id}

Get call details

GET/calls/{id}/recording

Create a short-lived playback link

GET/calls/{id}/recording/stream

Stream recording audioREST only

GET/calls/export.csv

Export calls as CSVREST only

Leads

Create, import, qualify, assign and annotate lead records.

GET/leads

List and filter leads

GET/leads/stats

Get lead statistics

GET/leads/{id}

Get lead details

POST/leads

Create a manual lead

POST/leads/import

Import leads

POST/leads/bulk

Update leads in bulk

PATCH/leads/{id}

Update and qualify a lead

POST/leads/{id}/notes

Add a lead note

GET/leads/export.csv

Export leads as CSVREST only

Reports and usage

Measure source performance, lead quality, activity, cost and margin.

GET/reports/dashboard

Get dashboard totals

GET/reports/timeseries

Get calls and leads over time

GET/reports/sources

Get source performance

GET/reports/lead-quality

Get lead quality breakdown

GET/reports/call-times

Get call time distribution

GET/reports/agency-overview

Compare clients agency-wide

GET/usage

Get usage totals

GET/usage/by-client

Get usage by client

GET/usage/margin

Get margin estimates

PUT/usage/margin/{clientId}

Set client billing and margin inputs

Recording and compliance

Control consent, playback, retention, export and recording deletion.

GET/compliance/recording-policies

List recording policies

GET/compliance/recording-policies/{clientId}

Get a client policy

PUT/compliance/recording-policies/{clientId}

Set consent and recording policy

GET/compliance/clients/{clientId}/data-export

Export all client dataREST only

POST/compliance/clients/{clientId}/purge

Purge client recordingsExternalDestructive

Audit and integrations

Inspect operational history and deliver LeadVouch events to other systems.

GET/audit

List audit events

GET/audit/errors

List operational errors

POST/audit/errors/{id}/resolve

Resolve an operational error

GET/webhooks/subscriptions

List outbound webhook subscriptions

POST/webhooks/subscriptions

Create a webhook subscription

PATCH/webhooks/subscriptions/{id}

Update a webhook subscription

DELETE/webhooks/subscriptions/{id}

Delete a webhook subscriptionDestructive

GET/webhooks/deliveries

List webhook deliveries

POST/webhooks/deliveries/{id}/replay

Replay a webhook deliveryExternal

POST/webhooks/subscriptions/{id}/test

Send a test webhookExternal

Ready to connect an agent?

Create a scoped token in LeadVouch Settings, start with purchases and destructive actions disabled, then connect through REST or MCP.

Open API token settings