Ringlane API reference (v1)

Being rolled out. The API is not yet available in every workspace. Until it is available in yours, requests return 403 api_disabled.

The API is part of the Pro and Business plans. The workspace owner creates access tokens in Ringlane under Settings › Developers, on the Access tokens tab, and webhooks on the Webhooks tab. In Dutch, the app shows Instellingen › Ontwikkelaars, with the tabs Toegangstokens and Webhooks.

Ringlane shows a token only once, when it is created, so store it in a secret store straight away. For the same steps without code, read the Academy guide Developers: API and access tokens.

The Ringlane API lets your own systems read and write the data of one Ringlane workspace: records (leads), campaigns, activities, tasks and meetings. Webhooks tell your server when something changes.

  1. Authentication
  2. Scopes
  3. Rate limits
  4. Errors
  5. Pagination
  6. Query parameters
  7. Endpoints
  8. Webhooks
  9. Security checklist for integrators

Authentication

Each request carries an access token in the Authorization header:

GET /api/v1/self HTTP/1.1
Host: app.ringlane.ai
Authorization: Bearer rl_4f1c…

Scopes

When the owner creates a token, they give it Off, Read or Read and write access to each area. Every area starts at Off.

ScopeLevelsEndpoints
recordsread, read_write/records, /records/{id}
campaignsread, read_write/campaigns, /campaigns/{id}
activitiesread, read_write/records/{id}/activities, POST /records/{id}/notes
tasksread, read_write/tasks, PUT/DELETE /records/{id}/task
meetingsread/meetings
membersread/members
fieldsread/fields

A request outside the token's scopes returns 403 insufficient_scope.

Rate limits

LimitValue
Per workspace, per minute120 requests
Per workspace, per day (UTC)20,000 requests
Request body100 KB
Page size1–100 (default 50)
Deletes500 records per 10 minutes

Every response carries the minute limit in three headers:

When you go over a limit, you get 429 with a Retry-After header in seconds.

Errors

Errors come back with an HTTP status and a body like this:

{ "error": { "code": "insufficient_scope", "message": "This token needs records: read_write. …" } }

Every response also carries an X-Request-Id. Mention it when you contact support.

StatusCodes
400bad_request, invalid_json, invalid_body, invalid_field, unknown_field, invalid_query, invalid_cursor, token_in_url, invalid_data
401invalid_token, token_expired, token_inactive
403insufficient_scope, plan_required, plan_limit, workspace_suspended (also while the workspace is scheduled for deletion), api_disabled
404not_found
405method_not_allowed
413payload_too_large
415unsupported_media_type
429rate_limited, daily_limit, too_many_deletes
500, 503server_error, service_unavailable: retry with backoff

Pagination

List endpoints return { "data": [...], "next_cursor": "…" | null }, sorted by id.

To get the next page, send cursor with the value of next_cursor. Stop when next_cursor is null. limit sets the page size, from 1 to 100.

Query parameters

ParameterUsed byMeaning
limitlistspage size, 1–100
cursorlistsfrom next_cursor
campaign_idGET /recordsonly records in this campaign
statusGET /recordsonly records with this status (see /fields)
updated_sinceGET /recordsISO 8601 time; records changed at or after it
assignee_idGET /tasksonly tasks for this member
due_beforeGET /tasksISO 8601 time
from, toGET /meetingsISO 8601 times; meetings in [from, to)

An unknown parameter returns 400 invalid_query, so a typo never passes silently.

Endpoints

GET /self

This endpoint needs no scope. It returns the token's workspace, its name, scopes and expiry, and the rate limits.

Records

A record is a lead your workspace uploaded or created.

{
  "id": "l3f9c0e1a2b4d5e6f7a8b",
  "company": "Acme NV", "first_name": "Ann", "last_name": "Peeters", "job_title": "CFO",
  "phone": "+3225550101", "direct_phone": "", "mobile_phone": "+32470123456", "gatekeeper": "",
  "email": "ann@acme.be", "website": "https://acme.be", "linkedin": "",
  "street": "", "postal_code": "2000", "city": "Antwerpen", "country": "BE", "sector": "Logistiek",
  "notes": "", "do_not_call": false,
  "campaign_id": "lijst_najaar_1a2b", "status": "In gesprek", "owner_id": "a3c8…",
  "attempts": 2, "last_contact_at": "2026-10-28T09:41:12.000Z", "meeting_at": null, "lost_reason": null,
  "next_task": { "due_at": "2026-11-03T09:00:00Z", "kind": "call", "note": "", "assignee_id": "a3c8…" },
  "custom_fields": { "omzet": 1200000 },
  "created_at": "2026-10-20T08:00:00.000Z", "created_by": "a3c8…", "updated_at": "2026-10-28T09:41:12.381+00:00"
}
EndpointScope
GET /recordsrecords: readList records, filtered by campaign_id, status or updated_since.
GET /records/{id}records: readOne record.
POST /recordsrecords: read_writeCreate a record. Body: {"data": {…}}. Returns 201.
PATCH /records/{id}records: read_writeChange fields. Fields you leave out stay as they are.
DELETE /records/{id}records: read_writeMoves the record to the trash. An owner or admin can restore it for 30 days.

Writable fields:

Unknown or read-only fields return 400 unknown_field. A status change also appears in the record's history in Ringlane as "(API)".

Activities and notes

EndpointScope
GET /records/{id}/activitiesactivities: readThe record's history, newest first: calls with their outcome, LinkedIn, email, WhatsApp, notes and status changes.
POST /records/{id}/notesactivities: read_writeBody: {"data": {"text": "…"}}, 1–2000 characters. Returns 201.

An activity looks like this:

Tasks

EndpointScope
GET /taskstasks: readOpen records with a next task, filtered by assignee_id or due_before.
PUT /records/{id}/tasktasks: read_writeBody: {"data": {"due_at": "2026-11-03T10:00:00+01:00", "kind": "call", "note": "…", "assignee_id": "…"}}. due_at needs a time zone. kind is call, linkedin, email or whatsapp.
DELETE /records/{id}/tasktasks: read_writeClears the next task.

Campaigns

EndpointScope
GET /campaignscampaigns: readList campaigns.
GET /campaigns/{id}campaigns: readOne campaign.
POST /campaignscampaigns: read_writeBody: {"data": {"name": "…", "source": "…", "status": "Actief", "goal": 20, "on_behalf_of": "…", "owner_id": "…"}}. name is required.
PATCH /campaigns/{id}campaigns: read_writeChange fields. status is Actief, Gepauzeerd or Afgerond.

Meetings, members and fields

EndpointScope
GET /meetingsmeetings: readRecords with a meeting (starts_at), filtered by from and to.
GET /membersmembers: readEach member's id, name, email, role (owner, admin, member or viewer), job_role, team, active and external.
GET /fieldsfields: readThe workspace's custom fields (key, label, type), statuses, task kinds and campaign statuses.

Webhooks

A webhook sends an HTTPS POST to your server when something changes in the workspace. The owner creates webhooks in Settings › Developers › Webhooks.

Events

Eventdata
record.createdrecord_id, campaign_id
record.updatedrecord_id, changed (the names of the changed fields, never their values)
record.deletedrecord_id
activity.createdrecord_id, activity_id, type, outcome
meeting.scheduledrecord_id, starts_at
campaign.createdcampaign_id
campaign.updatedcampaign_id, changed
campaign.deletedcampaign_id
pingwebhook_id (only the test message)

Payloads contain ids, never names, numbers or notes. Fetch what you need with the API and a token. This is deliberate: a payload that leaks or reaches the wrong place reveals nothing about your leads.

{ "id": "6b0e…", "type": "record.updated", "created_at": "2026-10-28T09:41:12.381+00:00",
  "workspace_id": "a1b2…", "data": { "record_id": "l3f9…", "changed": ["status", "next_task"] } }

Headers

Verifying the signature

Each webhook has its own signing secret (whsec_…). It is shown once, when the webhook is created or its secret is replaced.

v1 is the hex HMAC-SHA256 of "{t}.{raw body}", with the full secret as the key. To verify:

  1. Use the raw request body, exactly as received.
  2. Reject times older than 5 minutes; this protects against replay.
  3. Compare the signatures in constant time.
import crypto from 'node:crypto';
export function verify(secret, header, rawBody, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.trim().split('=')));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 || '', 'hex');
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}
import hmac, hashlib, time
def verify(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Delivery

Target URL rules

The target URL must use public https on port 443 with a valid certificate (TLS 1.2 or later). The following are refused:

Ringlane resolves the host name at every delivery. It refuses private, loopback, link-local, carrier-grade NAT, multicast and reserved addresses, including IPv6 forms that wrap an IPv4 address. It then connects only to the address it checked, which protects against DNS rebinding.

Developing locally

Webhooks are allowed during development, but always through a public HTTPS address. Run a tunnel to your machine and use its https:// URL as the target. Examples:

Plain http:// or localhost is never accepted, in development or production. Use the "Send test message" action to check your endpoint and signature verification.

Security checklist for integrators