LIO API Documentation

Product: LIO — Lead Intelligence (WorksBuddy suite) Last updated: 2026-06-15

LIO lets you capture, enrich, score, route, and manage leads and deals programmatically. Use the API to push leads from your own forms, apps, and ad platforms, read AI lead scores and intent signals, manage pipelines and deals, run reports, and keep your CRM data in sync.

Table of contents#

1. Getting started
2. Authentication
3. Requests and responses
4. Errors
5. Pagination, filtering, and sorting
6. Endpoint reference
7. Core resources in detail
8. Lead ingestion and web forms
9. Intent signals and email tracking
10. Public booking
11. Data models
12. Common integration use cases

1. Getting started#

LIO is multi-tenant: every record belongs to an organization, and your requests only ever see data from your own organization.

Endpoints are served under two path prefixes, /api and /api/v1. Use the exact path shown for each endpoint — both prefixes are available to any authenticated caller.

To make your first call:

1. Get a token with POST /api/auth/login.
2. Send that token in the Authorization header on every request.

2. Authentication#

Most endpoints authenticate with a bearer token that you obtain by logging in. Lead-ingestion endpoints can alternatively authenticate with an API key.

2.1 Log in and get a token#

POST /api/auth/login

Exchange your email and password for a bearer token.

Sample request:

Copycurl -X POST https://<host>/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "<your_password>"
  }'

Sample response (200 OK):

Copy{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "expires_at": "2026-07-15T09:14:32.000Z",
  "user": {
    "id": 142,
    "email": "you@company.com",
    "name": "Your Name",
    "organization_id": "org_...",
    "role_name": "Admin"
  }
}

The token is valid for 30 days (expires_in is in seconds). It scopes all data access to your organization automatically.

2.2 Use the token#

Send the token in the Authorization header on every request:

CopyAuthorization: Bearer <access_token>

A missing, malformed, or expired token returns 401.

2.3 API keys (for lead ingestion)#

For server-to-server lead capture you can use an API key instead of a bearer token. Create and manage keys from the LIO app (Settings → API Keys), then send the key as a header:

Copyx-api-key: <your_api_key>

API keys are accepted by the lead-ingestion and hosted-web-form endpoints described in Section 8. A key can be restricted to specific domains and IP addresses when you create it.

3. Requests and responses#

Most endpoints return a standard envelope:

Copy{ "success": true, "message": "...", "data": [], "total": 100, "page": 1, "limit": 10 }

On failure:

Copy{ "success": false, "error": { "message": "...", "type": "...", "code": null } }

A few endpoints (hosted forms, tracking pixels, redirects) return a non-JSON body appropriate to their purpose; these are called out where relevant.

Notes:

• All timestamps are ISO 8601.
• IDs are numeric.
• Requests are scoped to your organization; you never need to pass an organization identifier.

4. Errors#

Requests may be rate limited; if you receive 429, retry with exponential backoff.

API-key specific errors:

5. Pagination, filtering, and sorting#

List endpoints share a common query convention:

List responses return data alongside total, page, and limit. Most list endpoints also accept resource-specific filters; the important ones are noted per resource in Section 7.

6. Endpoint reference#

Endpoints are grouped by area. Unless an endpoint is documented as using an API key, it authenticates with the bearer token from Section 2.

In the Parameters column, bold fields are required and the rest are optional. :id and similar path values are shown in the path. List endpoints also accept the standard list parameters (page, limit, search_value, order_by, order_in, date range).

6.1 Authentication and users#

6.2 Leads#

See §7.1 for full field details on creating, updating, and filtering leads.

6.3 Lead enrichment#

6.4 Contacts and companies#

6.5 Custom fields, lookups, and views#

6.6 Pipelines and deals#

See §7.2 and §7.3 for full field details.

6.7 Forecasting#

6.8 Target accounts (ABM)#

6.9 AI tools and email#

AI generation features (magicpen, email generation, AI dashboards) consume credits from your organization's balance.

6.10 Dashboards and analytics#

6.11 Mail, inbox, calendar, and meetings#

Most inbox endpoints require config_id (the mail account ID) as a query parameter.

6.12 Voice and calling#

6.13 Intent signals and alerts#

6.14 Integrations (CRM import and messaging)#

6.15 Notifications, files, and exports#

7. Core resources in detail#

7.1 Leads#

List leads — GET /api/lead/list

In addition to the standard list parameters, leads support:

Create a lead — POST /api/lead/add

Update a lead — POST /api/lead/update/:id

Accepts any creatable field. custom_fields and ai_information are merged into the existing values.

Bulk actions — status change, assignment, and tagging accept either an explicit ids array or select_all: true with a filters object to act on every lead matching the current filter.

7.2 Deals#

Create a deal — POST /api/lead/deal/add

List deals — GET /api/lead/deal/list supports lead_id, pipeline_id, status (stage ID), and date-range filters alongside the standard list parameters.

7.3 Pipelines#

Create a pipeline — POST /api/pipelines/add

Some pipeline stages are protected and cannot be changed or removed.

8. Lead ingestion and web forms#

These endpoints let external systems push leads into LIO. They accept an API key (x-api-key) instead of a bearer token.

8.1 Create a lead#

POST /api/v1/lead

Creates a lead in the organization that owns the API key. Provide at least one of email, phone_number, or linkedin_url.

Sample request:

Copycurl -X POST https://<host>/api/v1/lead \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "first_name": "Jane",
    "company": "Acme Corp",
    "lead_source": 1
  }'

Sample response:

Copy{
  "success": true,
  "message": "Lead created successfully",
  "data": {
    "id": 80231,
    "email": "jane@acme.com",
    "first_name": "Jane",
    "company": "Acme Corp",
    "status": 1,
    "priority": 2,
    "score": 0,
    "created_at": "2026-06-15T09:14:32.000Z"
  }
}

A duplicate (same email or LinkedIn URL) returns 409. To accept it anyway, send duplicate: 1; to update the existing lead instead, send merge: 1. Any field not listed above is stored under custom_fields. AI scoring fields populate shortly after creation.

8.2 List leads via API key#

GET /api/v1/lead/lead-list — paginated list of the key's organization. Supports page, limit, search_value, order_by, and order_in.

8.3 Hosted web form#

GET /api/v1/web-form/:form_link — returns a hosted lead-capture form. Submissions create leads in the form's organization. Build and manage forms in the LIO app.

9. Intent signals and email tracking#

9.1 Log an intent signal#

POST /api/v1/intent-signal

Record a behavioral signal against a lead. Resulting hot leads surface through GET /api/intent-alert/hot-leads.

signal_type values: pricing_page_visit, demo_requested, form_submitted, reply_received, email_opened, email_opened_3x, link_clicked, case_study_download, manual.

9.2 Email tracking#

Embed these in outbound email to capture engagement:

Opens and clicks generate email_opened and link_clicked intent signals automatically.

10. Public booking#

These endpoints back a public scheduling page and require no authentication.

Confirm a booking — POST /api/v1/booking/:slug/confirm

11. Data models#

Core objects and their main fields. Read-only fields are populated by LIO and cannot be set directly.

Lead#

Resolved labels status_text, priority_text, and lead_source_text are returned for convenience.

Deal#

Contact#

Company#

Pipeline and stage#

Pipeline: id, name, description, max_deal_limit, region, state_id (1=Active, 0=Inactive).

Stage: id, pipeline_id, name, color, position, is_won, is_lost, probability (0–1), max_days_in_stage.

Meeting#

id, user_id, lead_id / contact_id / company_id, title, description, location, start_time, end_time, timezone, attendees, meeting_url, meeting_tool (meet/teams/zoom/custom/none), status (1=Scheduled, 2=Rescheduled, 3=Held, 4=Cancelled, 5=No Show).

Call#

id, user_id, lead_id / contact_id / company_id, direction (inbound/outbound), from_number / to_number, status, started_at / answered_at / ended_at, duration_sec, transcript, price.

12. Common integration use cases#

1. Push leads from your own form or app — POST /api/v1/lead with an API key.
2. Host a lead-capture form — embed GET /api/v1/web-form/:form_link; submissions become leads.
3. Sync deal stages from another system — list deals with GET /api/lead/deal/list, then update with POST /api/lead/deal/update/:id.
4. Feed behavioral intent signals — POST /api/v1/intent-signal, then read hot leads via GET /api/intent-alert/hot-leads.
5. Track email engagement — embed the open pixel and click redirect from Section 9.
6. Offer public booking — GET /api/v1/booking/:slug → /availability → POST .../confirm.
7. Import an existing CRM — POST /api/connected-apps/hubspot/import, then poll the import status endpoint.
8. Bulk import from a spreadsheet — POST /api/lead/lead-imports, then poll GET /api/import-job/list.