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.
- Base URL:
https://app.ringlane.ai/api/v1 - Format: JSON in, JSON out (UTF-8).
- Availability: the Pro and Business plans. Only the workspace owner can create access tokens and webhooks. This happens in Settings › Developers.
- Authentication
- Scopes
- Rate limits
- Errors
- Pagination
- Query parameters
- Endpoints
- Webhooks
- 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…
- Token format. A token is
rl_followed by 64 lowercase hexadecimal characters. The prefix makes leaked tokens easy to recognise in code and logs. - Shown once. Ringlane shows a token once, when it is created. It stores only a SHA-256 fingerprint and cannot show the token again. If you lose it, create a new one.
- Never in a URL. A token in a query string (
?token=,?access_token=,?api_key=and similar) is refused with400 token_in_url. - One workspace. A token belongs to exactly one workspace. That workspace comes from the token alone. A workspace id in a request is ignored, and an id from another workspace returns
404. - Expiry. A token expires after 7, 30, 90 (the default) or 365 days. A token also stops working at once when:
- it is revoked;
- its creator is no longer an owner of the workspace;
- the workspace is suspended;
- the workspace leaves the Pro or Business plan.
- No browser use. The API sends no CORS headers, so a web page on another site cannot call it. Call the API from a server, never from front-end code.
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.
| Scope | Levels | Endpoints |
|---|---|---|
records | read, read_write | /records, /records/{id} |
campaigns | read, read_write | /campaigns, /campaigns/{id} |
activities | read, read_write | /records/{id}/activities, POST /records/{id}/notes |
tasks | read, read_write | /tasks, PUT/DELETE /records/{id}/task |
meetings | read | /meetings |
members | read | /members |
fields | read | /fields |
A request outside the token's scopes returns 403 insufficient_scope.
Rate limits
| Limit | Value |
|---|---|
| Per workspace, per minute | 120 requests |
| Per workspace, per day (UTC) | 20,000 requests |
| Request body | 100 KB |
| Page size | 1–100 (default 50) |
| Deletes | 500 records per 10 minutes |
Every response carries the minute limit in three headers:
X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset, a Unix time.
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.
| Status | Codes |
|---|---|
| 400 | bad_request, invalid_json, invalid_body, invalid_field, unknown_field, invalid_query, invalid_cursor, token_in_url, invalid_data |
| 401 | invalid_token, token_expired, token_inactive |
| 403 | insufficient_scope, plan_required, plan_limit, workspace_suspended (also while the workspace is scheduled for deletion), api_disabled |
| 404 | not_found |
| 405 | method_not_allowed |
| 413 | payload_too_large |
| 415 | unsupported_media_type |
| 429 | rate_limited, daily_limit, too_many_deletes |
| 500, 503 | server_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
| Parameter | Used by | Meaning |
|---|---|---|
limit | lists | page size, 1–100 |
cursor | lists | from next_cursor |
campaign_id | GET /records | only records in this campaign |
status | GET /records | only records with this status (see /fields) |
updated_since | GET /records | ISO 8601 time; records changed at or after it |
assignee_id | GET /tasks | only tasks for this member |
due_before | GET /tasks | ISO 8601 time |
from, to | GET /meetings | ISO 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"
}
| Endpoint | Scope | |
|---|---|---|
GET /records | records: read | List records, filtered by campaign_id, status or updated_since. |
GET /records/{id} | records: read | One record. |
POST /records | records: read_write | Create a record. Body: {"data": {…}}. Returns 201. |
PATCH /records/{id} | records: read_write | Change fields. Fields you leave out stay as they are. |
DELETE /records/{id} | records: read_write | Moves the record to the trash. An owner or admin can restore it for 30 days. |
Writable fields:
company,first_name,last_name,job_titlephone,direct_phone,mobile_phone: international E.164 format, like+32470123456gatekeeperemail: a valid address; it is stored in lowercasewebsite,linkedin: start withhttps://orhttp://street,postal_code,citycountry: an ISO 3166 two-letter codesector,notescampaign_id: an existing campaign in this workspacestatus: one of the statuses from/fieldsowner_id: an active memberdo_not_call: a booleancustom_fields: keys from/fields;nullclears a value
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
| Endpoint | Scope | |
|---|---|---|
GET /records/{id}/activities | activities: read | The record's history, newest first: calls with their outcome, LinkedIn, email, WhatsApp, notes and status changes. |
POST /records/{id}/notes | activities: read_write | Body: {"data": {"text": "…"}}, 1–2000 characters. Returns 201. |
An activity looks like this:
idtype:call,linkedin,email,whatsapp,noteorsystemoutcome: for a call,nb(not reached),ges(conversation),tb(call back),afs(meeting),gi(not interested) orong(invalid number)label,textdirection:inoroutoccurred_at,created_byduration_seconds,next_task_at,lost_reason
Tasks
| Endpoint | Scope | |
|---|---|---|
GET /tasks | tasks: read | Open records with a next task, filtered by assignee_id or due_before. |
PUT /records/{id}/task | tasks: read_write | Body: {"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}/task | tasks: read_write | Clears the next task. |
Campaigns
| Endpoint | Scope | |
|---|---|---|
GET /campaigns | campaigns: read | List campaigns. |
GET /campaigns/{id} | campaigns: read | One campaign. |
POST /campaigns | campaigns: read_write | Body: {"data": {"name": "…", "source": "…", "status": "Actief", "goal": 20, "on_behalf_of": "…", "owner_id": "…"}}. name is required. |
PATCH /campaigns/{id} | campaigns: read_write | Change fields. status is Actief, Gepauzeerd or Afgerond. |
Meetings, members and fields
| Endpoint | Scope | |
|---|---|---|
GET /meetings | meetings: read | Records with a meeting (starts_at), filtered by from and to. |
GET /members | members: read | Each member's id, name, email, role (owner, admin, member or viewer), job_role, team, active and external. |
GET /fields | fields: read | The 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
| Event | data |
|---|---|
record.created | record_id, campaign_id |
record.updated | record_id, changed (the names of the changed fields, never their values) |
record.deleted | record_id |
activity.created | record_id, activity_id, type, outcome |
meeting.scheduled | record_id, starts_at |
campaign.created | campaign_id |
campaign.updated | campaign_id, changed |
campaign.deleted | campaign_id |
ping | webhook_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
Ringlane-Signature:t=<unix time>,v1=<signature>(see below).Ringlane-Event: the event type.Ringlane-Delivery: the id of this delivery attempt.Idempotency-Key: the eventid. It is the same on every retry, so you can drop duplicates.User-Agent:Ringlane-Webhooks/1.0 (+https://ringlane.ai/developers).
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:
- Use the raw request body, exactly as received.
- Reject times older than 5 minutes; this protects against replay.
- 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
- Success. Any
2xxresponse within 10 seconds. Answer quickly, then do the work afterwards. - No redirects. A
3xxcounts as a failure. - Retries. After a failure Ringlane retries after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h and 24 h. That is 9 attempts over about 3 days.
- Order. Events are delivered at least once and not always in order. Use
Idempotency-Keyand fetch the current state with the API. - Automatic switch-off. A webhook that has only failed for 72 hours is switched off. Pending deliveries are then cancelled. The owner sees this in Settings and can switch the webhook back on.
- Delivery log. The owner sees each webhook's last 50 deliveries and can retry a failed one.
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:
http, other ports, and a user name or password in the URL;- IP addresses,
localhost, and internal or reserved names (.local,.internal,.test,example.com, …); - Ringlane's own domains and the domains of its hosting providers.
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:
ngrok http 3000cloudflared tunnel --url http://localhost:3000
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
- Keep tokens in a secret store, such as your platform's environment secrets or a password manager. Never put them in code, Git, front-end bundles, URLs, documents or chat.
- Give each integration its own token with the smallest scopes it needs and the shortest practical expiry. Revoke tokens you no longer use.
- Verify every webhook signature and its timestamp. Process each event id only once.
- Rotate a webhook secret when someone who knew it leaves, or when you suspect a leak.