Your data, anywhere you need it

Overview

The Persilio API is a REST API over HTTPS with JSON responses. It exposes your leads — including the complete acquisition attribution and visitor journey behind each one — your lead and traffic analytics, and, for organizations with a Persilio-managed website, the website CMS: read and edit pages as content blocks and publish the site.

Base URL:   https://api.persilio.com/api/v1
MCP server: https://api.persilio.com/mcp

Authentication

Every request is authenticated with an org-scoped API key. Create one in the dashboard under Settings → API access (owners and managers only). The key is shown once at creation — store it like a password. Keys can be revoked at any time from the same screen, and revocation takes effect immediately.

Send the key as a bearer token on every request:

Authorization: Bearer psk_live_4f8a2c…

• A key only ever sees the organization it was created in.
• Keys are stored hashed — Persilio cannot show you a key again after creation.
• A key acts as one person and carries scopes that are the dashboard's own areas — leads, contacts, messages, billing, analytics, reports, reviews, cms, seo and the rest of the sidebar. A key can never reach more than its holder can open in the dashboard, and it follows any change to that person's access on the Team page. A scoped key only reaches endpoints covered by its scopes, so a build-server key can render reviews without ever being able to read customer PII. A key with no scopes has everything its holder has.
• The leads and analytics surfaces are read-only. Writes live behind explicit scopes: cms edits website content, billing creates and edits quotes, invoices, templates and e-signature links, and contacts manages the contact book.

Rate limits

Each key may make 120 requests per minute with bursts up to 30. The MCP server draws from the same budget. Over the limit, requests return 429 with a Retry-After header (in seconds) — wait that long and retry.

HTTP/2 429
Retry-After: 12

{ "error": { "message": "Rate limit exceeded.", "status": 429 } }

Conventions & pagination

• Timestamps are Unix epoch milliseconds everywhere — request parameters and response fields alike.
• Optional fields with no value are omitted from responses, not returned as null. Code defensively: lead.gclid ?? null.
• IDs are opaque strings. Don't parse them; store and compare them as-is.
• Dates in analytics (byDay) are UTC calendar days.

Pagination

GET /leads paginates with an opaque numeric cursor. Fetch the first page normally; while the response's nextCursor is non-null, request the next page with cursor=<nextCursor>. When it comes back null, you have everything.

# page 1
curl -s "https://api.persilio.com/api/v1/leads?limit=100" -H "Authorization: Bearer $KEY"
# → { "leads": [ …100 leads… ], "nextCursor": 1750912345678 }

# page 2
curl -s "https://api.persilio.com/api/v1/leads?limit=100&cursor=1750912345678" -H "Authorization: Bearer $KEY"
# → { "leads": [ …remaining leads… ], "nextCursor": null }

Endpoints

curl -s https://api.persilio.com/api/v1/me \
  -H "Authorization: Bearer psk_live_…"

{
  "orgId": "kd701nhcc2qedbce39g2qjzp8x826em9",
  "org": {
    "name": "Example HVAC Co",
    "domain": "example-hvac.com",
    "websiteUrl": "https://www.example-hvac.com",
    "businessPhone": "+15551234567"
  },
  "key": { "name": "Reporting script" }
}

# Most recent 50 leads
curl -s "https://api.persilio.com/api/v1/leads?limit=50" \
  -H "Authorization: Bearer psk_live_…"

# New PPC leads from June 2026
curl -s "https://api.persilio.com/api/v1/leads?status=new&channel=ppc&createdAfter=1780272000000&createdBefore=1782864000000" \
  -H "Authorization: Bearer psk_live_…"

# Search by name / email / phone
curl -s "https://api.persilio.com/api/v1/leads?query=jane" \
  -H "Authorization: Bearer psk_live_…"

{
  "leads": [
    {
      "id": "kd74x8m2p9qfz3hcvw6t5n1jrb89kd2e",
      "createdAt": 1751212345678,
      "cameInAt": 1751212345678,
      "name": "Jane Example",
      "email": "jane@example.com",
      "phone": "5551234567",
      "message": "Our AC went out yesterday — looking for a repair quote this week.",
      "status": "contacted",
      "source": "website_form",
      "sourceLabel": "AC Repair",
      "channel": "ppc",
      "referrer": "https://www.google.com/",
      "landingPage": "/services/ac-repair",
      "sourceUrl": "https://www.example-hvac.com/services/ac-repair",
      "utmSource": "google",
      "utmMedium": "cpc",
      "utmCampaign": "summer-ac-repair",
      "utmTerm": "ac repair near me",
      "utmContent": "ad-variant-b",
      "gclid": "EAIaIQobChMI8p2c4vHq9gIVxxWtBh2QkQAxEAAYASAAEgL",
      "sessionId": "b3f09c41-77aa-4c1e-9f2d-2f4e8d1c6a55",
      "visitorId": "9a1c3f7e-d2b8-4e06-8f31-5c7a2e9d4b10",
      "contactId": "s17k2m9w4rvq8n3xzp6c1f5hjd89tm3a",
      "pipelineStage": "Contacted",
      "notes": ["Called back — wants an estimate Thursday morning."],
      "lastActivityAt": 1751215600000
    }
  ],
  "nextCursor": 1750912345678
}

curl -s https://api.persilio.com/api/v1/leads/kd74x8m2p9qfz3hcvw6t5n1jrb89kd2e \
  -H "Authorization: Bearer psk_live_…"

{
  "id": "kd74x8m2p9qfz3hcvw6t5n1jrb89kd2e",
  "createdAt": 1751212345678,
  "cameInAt": 1751212345678,
  "name": "Jane Example",
  "email": "jane@example.com",
  "phone": "5551234567",
  "message": "Our AC went out yesterday — looking for a repair quote this week.",
  "status": "contacted",
  "source": "website_form",
  "sourceLabel": "AC Repair",
  "channel": "ppc",
  "referrer": "https://www.google.com/",
  "landingPage": "/services/ac-repair",
  "sourceUrl": "https://www.example-hvac.com/services/ac-repair",
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "summer-ac-repair",
  "utmTerm": "ac repair near me",
  "utmContent": "ad-variant-b",
  "gclid": "EAIaIQobChMI8p2c4vHq9gIVxxWtBh2QkQAxEAAYASAAEgL",
  "sessionId": "b3f09c41-77aa-4c1e-9f2d-2f4e8d1c6a55",
  "visitorId": "9a1c3f7e-d2b8-4e06-8f31-5c7a2e9d4b10",
  "contactId": "s17k2m9w4rvq8n3xzp6c1f5hjd89tm3a",
  "pipelineStage": "Contacted",
  "notes": ["Called back — wants an estimate Thursday morning."],
  "lastActivityAt": 1751215600000,
  "contact": {
    "id": "s17k2m9w4rvq8n3xzp6c1f5hjd89tm3a",
    "name": "Jane Example",
    "firstName": "Jane",
    "lastName": "Example",
    "email": "jane@example.com",
    "phone": "5551234567",
    "company": "Example Property Management"
  },
  "activities": [
    { "type": "status_change", "content": "Status changed from new to contacted", "timestamp": 1751215600000, "authorName": "Alex Rivera" },
    { "type": "note", "content": "Called back — wants an estimate Thursday morning.", "timestamp": 1751215500000, "authorName": "Alex Rivera" },
    { "type": "lead_created", "content": "New lead from website form", "timestamp": 1751212345678, "authorName": "System" }
  ],
  "journey": {
    "sessionId": "b3f09c41-77aa-4c1e-9f2d-2f4e8d1c6a55",
    "visitorId": "9a1c3f7e-d2b8-4e06-8f31-5c7a2e9d4b10",
    "startedAt": 1751212001000,
    "lastSeenAt": 1751212390000,
    "landingPage": "/services/ac-repair",
    "landingUrl": "https://www.example-hvac.com/services/ac-repair?utm_source=google&utm_medium=cpc",
    "referrer": "https://www.google.com/",
    "channel": "ppc",
    "sourceLabel": "Google Ads",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "summer-ac-repair",
    "utmTerm": "ac repair near me",
    "utmContent": "ad-variant-b",
    "gclid": "EAIaIQobChMI8p2c4vHq9gIVxxWtBh2QkQAxEAAYASAAEgL",
    "device": { "type": "mobile", "browser": "Safari", "browserVersion": "18.5", "os": "iOS", "osVersion": "18.5" },
    "geo": { "country": "US", "region": "TX", "city": "Austin" },
    "isReturning": true,
    "visitNumber": 3,
    "pageviews": [
      { "path": "/services/ac-repair", "title": "AC Repair", "timestamp": 1751212001200, "durationMs": 42000 },
      { "path": "/reviews", "title": "Reviews", "timestamp": 1751212043200, "durationMs": 28000 },
      { "path": "/contact", "title": "Contact Us", "timestamp": 1751212071200, "durationMs": 61000 }
    ],
    "events": [
      { "type": "scroll_depth", "path": "/services/ac-repair", "timestamp": 1751212030000, "scrollDepth": 75 },
      { "type": "tel_click", "path": "/services/ac-repair", "timestamp": 1751212040000, "elementText": "(555) 123-4567" },
      { "type": "form_start", "path": "/contact", "timestamp": 1751212080000, "formName": "contact", "fieldName": "name" },
      { "type": "form_submit", "path": "/contact", "timestamp": 1751212335000, "formName": "contact" }
    ],
    "otherVisits": [
      { "startedAt": 1750901000000, "landingPage": "/", "channel": "organic", "referrer": "https://www.google.com/" },
      { "startedAt": 1751050000000, "landingPage": "/reviews", "channel": "direct" }
    ]
  }
}

# Default range (last 30 days)
curl -s https://api.persilio.com/api/v1/analytics/leads \
  -H "Authorization: Bearer psk_live_…"

# Explicit range — June 2026 (ms timestamps)
curl -s "https://api.persilio.com/api/v1/analytics/leads?since=1780272000000&until=1782864000000" \
  -H "Authorization: Bearer psk_live_…"

# Tip: build ms timestamps from a date
date -d "2026-06-01" +%s000        # linux
python3 -c "import datetime; print(int(datetime.datetime(2026,6,1).timestamp()*1000))"

{
  "range": { "since": 1780272000000, "until": 1782864000000 },
  "total": 42,
  "jobApplicationsExcluded": 3,
  "byChannel": { "organic": 18, "ppc": 12, "direct": 7, "referral": 3, "ai": 2 },
  "bySource": { "AC Repair": 21, "Furnace Install": 11, "(none)": 10 },
  "byStatus": { "new": 9, "contacted": 14, "scheduled": 8, "closed": 7, "lost": 4 },
  "byDay": [
    { "date": "2026-06-01", "count": 2 },
    { "date": "2026-06-02", "count": 1 }
  ],
  "truncated": false
}

curl -s "https://api.persilio.com/api/v1/analytics/traffic?since=1780272000000&until=1782864000000" \
  -H "Authorization: Bearer psk_live_…"

{
  "range": { "since": 1780272000000, "until": 1782864000000 },
  "sessions": 4064,
  "pageviews": 2905,
  "returningSessions": 312,
  "sessionsWithLead": 6,
  "byChannel": { "direct": 3536, "organic": 441, "referral": 69, "ai": 11, "social": 7 },
  "byDevice": { "mobile": 2983, "desktop": 1080, "tablet": 1 },
  "byCountry": [
    { "key": "US", "count": 3901 },
    { "key": "CA", "count": 82 }
  ],
  "byDay": [
    { "date": "2026-06-01", "count": 141 },
    { "date": "2026-06-02", "count": 129 }
  ],
  "topReferrers": [
    { "key": "https://www.google.com/", "count": 431 },
    { "key": "https://chatgpt.com/", "count": 6 }
  ],
  "topLandingPages": [
    { "key": "/", "count": 1512 },
    { "key": "/services/ac-repair", "count": 244 }
  ],
  "topPages": [
    { "key": "/", "count": 794 },
    { "key": "/contact", "count": 248 }
  ],
  "truncated": false
}

Object reference

Attribution values

channel

Persilio's resolved acquisition channel, computed first-touch from the visitor's original session — not the last click before the form submit. Raw signals (referrer, UTMs, click IDs) are always included alongside it so you can apply your own model.

status

Lead statuses, in rough pipeline order:

source

How the lead entered Persilio: website_form (submitted a tracked form), organic_call / ppc_call (call tracking), or manual (entered by your team).

Journey event types

Website CMS

Organizations with a Persilio-managed website can read and edit its pages through the API — the same content the dashboard's website editor manages. Every CMS route requires the cms scope (or an unscoped key). Edits always land in a page's draft; nothing changes on the live site until a publish.

The block model

A page is an ordered list of blocks: { id, kind, props, hidden? }. The block kinds a site supports — and the exact fields each kind's props accepts — are defined per site and returned as blockDefs by GET /cms/sites and on every page response. Writes are validated against those definitions, and validation failures come back as readable 400 messages naming the block and field.

# A page's draft, abridged
{
  "id": "…", "slug": "index", "path": "/", "title": "Home",
  "blocks": [
    { "id": "1f3…", "kind": "hero",
      "props": { "heading": "Injured? We can help.", "sub": "…" } },
    { "id": "9ab…", "kind": "faq",
      "props": { "items": [ { "q": "…", "a": "…" } ] } }
  ],
  "blockDefs": [ …the schema each kind accepts… ]
}

Editing

For a single change, prefer the block-level operation — it can't accidentally drop content:

# Change one block's heading
curl -s -X POST "https://api.persilio.com/api/v1/cms/pages/{pageId}/blocks" \
  -H "Authorization: Bearer psk_live_…" -H "Content-Type: application/json" \
  -d '{ "action": "edit", "blockId": "1f3…",
        "props": { "heading": "New headline" } }'

# action: "add"    → { kind, props?, afterBlockId? }
# action: "remove" → { blockId }

POST /cms/pages/{id} replaces the draft wholesale (title, SEO, and/or the full blocks array — use it for reorders). If the submitted array would drop existing block ids, the call is rejected unless allowRemovals: true — so partial payloads can never silently delete content.

Publishing

POST /cms/publish promotes every page with draft changes (narrow with pageIds), commits the site's content to its GitHub repository, and triggers a redeploy. It returns 202 with a publish id; poll GET /cms/publishes/{id} for progress. Only one publish runs at a time per site — a second request returns 400 until the first resolves.

Every publish is attributed (dashboard user, API key name, or MCP) in the page's version history, and the git history of the site repository carries a full diff of every publish.

Errors

Errors return a JSON body with the shape { "error": { "message", "status" } }.

Analytics responses additionally include a truncated flag when a very large range hit the per-request scan cap — narrow the since/until window if you see it set.

MCP server for AI agents

Persilio ships a hosted Model Context Protocol server, so AI agents and assistants can work with your Persilio data directly, with no glue code: read leads and analytics and, where a key allows it, edit your website and training courses. It speaks Streamable HTTP and accepts two forms of authentication: the same API keys as the REST API (as a bearer header), or the built-in OAuth flow for clients that can't send headers — which is how claude.ai custom connectors work.

https://api.persilio.com/mcp

Available tools

Each tool wraps the corresponding REST endpoint, so the parameters and response shapes documented above apply directly.

Connect from claude.ai or Claude Desktop (custom connector)

Claude's custom connectors authenticate with OAuth — the Persilio MCP server implements the full flow, so no configuration files are needed:

1. In claude.ai (or Claude Desktop), open Settings → Connectors → Add custom connector.
2. Name it Persilio and enter the server URL: https://api.persilio.com/mcp
3. Leave the OAuth Client ID and Secret fields under Advanced settings empty — Claude registers itself automatically.
4. Click Add, then Connect. A Persilio authorization page opens.
5. Paste an API key from Dashboard → Settings → API access and click Authorize. You're redirected back to Claude with the connector active.

The connector receives a token tied to the API key you pasted — revoking that key in your dashboard disconnects the connector immediately. It can do exactly what that key allows and nothing more: a key is limited to the areas you tick when you create it (and to the areas its holder can open in the dashboard), and it only ever reaches your organization. Claude lists the tools in two groups — read-only, and tools that change things — so you can let it read freely and still be asked before every edit.

Edit your training courses from Claude

To let Claude maintain your courses, create a key with only the Courses area ticked and connect it as above. Then talk to it the way you would to an editor:

• "Find every lesson that mentions our 60-day probation period and change it to 90 days."
• "Rewrite the Reporting an Injury on the Job lesson at a fifth-grade reading level. Show me before you save."
• "Add a three-question quiz to the end of Customer Communication Standards."
• "Move Vehicle Inspection Checklist into the Safety module and set it back to draft."
• "Here's a photo of the correct PPE setup — put it at the top of the Job Site Safety lesson with a caption."

Edits are live as soon as Claude makes them, and new lessons stay drafts until you publish them. A photo dropped into the chat can't be read by a connector, so Claude hands you an upload link instead: open it, drop the file, tell Claude it's there, and it places the image in the lesson. The file is kept under Documents → Course Media.

When new tools are added to the connector: Claude keeps a copy of a connector's tool list. If a tool described here is missing in your chat, open Settings → Connectors, click Persilio, and choose Refresh tools list. If that doesn't pick it up, add the connector again with https://api.persilio.com/mcp?v=2 as the URL.

Connect from Claude Code

claude mcp add --transport http persilio https://api.persilio.com/mcp \
  --header "Authorization: Bearer psk_live_…"

Connect from Cursor / other MCP clients

Clients that support custom headers can send the API key directly. Clients that only support OAuth (like claude.ai above) work through the built-in flow automatically. The generic header-based configuration shape:

{
  "mcpServers": {
    "persilio": {
      "url": "https://api.persilio.com/mcp",
      "headers": {
        "Authorization": "Bearer psk_live_…"
      }
    }
  }
}

Once connected, ask things like "how many organic leads did we get this month?", "show me the full journey behind our newest lead", or "which landing pages are converting?" — the agent pulls live data through the tools above.