The public API opens your Lyane workspace’s data to your own tools: an ERP, a sync script, an automation tool. It reads and writes clients, contacts, opportunities and tasks, and reads quotes, invoices and documents.
It is included in the Enterprise plan. Every URL starts with https://api.lyane.app/public/v1; bodies are JSON and instants follow ISO 8601, in UTC.
To get a key, a workspace administrator opens the app, then Settings → API. They give it a name and choose the domains it can access. Copy the key as soon as it is created and keep it in a secrets manager: the API never returns it in clear text, and only its prefix (lyk_ab12cd) identifies it afterwards.
What the API creates or updates appears in the app under the workspace’s “API” service account (field createdBy). A member assigned a task through the API is notified just as in the app.
The OpenAPI 3.1 specification describes every route: import it into your HTTP client (Postman, Insomnia, Bruno…) or a code generator.openapi.json
Authentication
Every request presents the key in the Authorization header, using the Bearer scheme. A missing, unknown, revoked or expired key gets a 401 response with the code invalid_api_key.
HTTP
Authorization: Bearer lyk_…
GET /me checks a key: it returns its workspace, name, prefix, permissions and expiry date.
A key only opens the domains chosen when it was created, each at one of three levels:
NoneNONE — the domain stays closed to the key.
ReadREAD — list and retrieve.
Read and writeWRITE — list and retrieve, and also create, update and delete.
Domain
What it opens
clients
Clients and prospects, companies and individuals.
contacts
Contact records shared with the team.
opportunities
Opportunities, sales pipelines and their stages.
tasks
Tasks and follow-ups.
sales
Quotes and invoices, read-only.
documents
Files stored on client records, read-only.
A call outside the key’s permissions gets 403 insufficient_scope, with the missing domain (domain) and the level required (required). Deleting a client also deletes its opportunities and its draft quotes and invoices: write access to opportunities and sales is then required.
Expiry and revocation
A key can have an expiry date (expiresAt in GET /me, null if it never expires). After that date, it is rejected with 401 invalid_api_key.
An administrator can revoke a key at any time in Settings → API: it is then rejected the same way. To rotate keys without downtime, create the new one, deploy it, then revoke the old one.
The workspace can also restrict the API to a list of IP addresses (403 ip_not_allowed outside it), and a plan without the API gets 403 feature_not_included.
Rate limits
Each key has 600 requests per minute and 50,000 requests per day (UTC day). Every response tells you where the per-minute limit stands:
Beyond that, the API responds 429 with a Retry-After header, in seconds, and the code rate_limited (per-minute limit) or quota_exceeded (daily quota). Wait for the given delay before retrying instead of retrying straight away.
HTTP
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 18
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 18
{
"type": "about:blank",
"title": "Too Many Requests",
"status": 429,
"detail": "Trop de requêtes pour cette clé : réessayez dans 18 secondes.",
"code": "rate_limited",
"retryAfter": 18
}
Pagination
Lists use cursor pagination and are sorted by last update (updatedAt), then by identifier: the order stays stable even when items change between two pages.
Parameter
Purpose
limit
The number of items per page, from 1 to 200 (50 by default).
cursor
The nextCursor of the previous page, as is. An unreadable cursor gets 400 invalid_cursor.
updatedSince
An ISO 8601 instant in UTC: only what was created or updated since then, inclusive.
The response holds the page (data) and the next cursor (nextCursor); null means it was the last page. To sync, record the instant each run starts and pass it as updatedSince on the next one: only items created or updated in between come back.
A creation (POST) can carry an Idempotency-Key header: a value unique to that creation, 1 to 255 characters long, a UUID for example. Replayed with the same key within 24 hours, after a network failure for example, the request gets the original response, with the header Idempotent-Replayed: true, and nothing is created twice.
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.lyane.app/public/v1/clients/3fa85f64-5717-4562-b3fc-2c963f66afa6
Idempotent-Replayed: true
The same key with a different body gets 409 idempotency_key_reused. If the first request is still running, 409 idempotency_key_in_progress: try again a little later.
Errors
Errors follow RFC 9457 (application/problem+json). The code field is stable: it is what your integration should read. detail explains the error in French, for a human, and may change.
HTTP
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"detail": "Cette clé n’a pas le droit WRITE sur le domaine opportunities.",
"code": "insufficient_scope",
"domain": "opportunities",
"required": "WRITE"
}
Code
Status
Meaning
validation_failed
400
A field is rejected: errors lists each field (field) and the reason (message).
invalid_cursor
400
The cursor is not a nextCursor returned by the API.
malformed_request
400
The request is malformed: an unreadable JSON body, for example.
custom_field_invalid
400
A custom field is rejected: fields gives each one’s key, label and reason (reason: required, invalid_type, unknown_option…).
invalid_filter
400
A cf.<key> filter targets an unknown or archived field, or its value is unreadable.
invalid_api_key
401
The key is missing, unknown, revoked or expired.
insufficient_scope
403
The key lacks the permission: domain gives the domain, required the level.
feature_not_included
403
The workspace’s plan does not include the API (or, for /custom-fields, custom fields).
ip_not_allowed
403
The caller’s IP address is not in the list allowed by the workspace.
not_found
404
The resource does not exist, or belongs to another workspace.
idempotency_key_reused
409
This Idempotency-Key was already used with a different body.
idempotency_key_in_progress
409
The first request with this Idempotency-Key is still running.
plan_limit_reached
409
The plan’s limit is reached (the number of clients, for example).
conflict
409
Another write changed the resource at the same time: read it again, then retry.
workspace_suspended
423
The workspace is blocked: it can still be read, but nothing can be written.
rate_limited
429
The per-minute limit is reached: wait Retry-After seconds.
quota_exceeded
429
The daily quota (UTC) is reached.
pdf_not_ready
503
The PDF is still being generated: try again in a few seconds.
Example: create a client, then an opportunity
With a key that has write access to clients and opportunities, stored in the LYANE_API_KEY environment variable:
Every route, grouped by domain, with its parameters, a request and response example, and the permission it requires. This reference is generated from the OpenAPI specification.
Key
The key in use and its workspace. No domain required.
The key and its workspace
GET/me
The workspace the key belongs to, and the key’s name, prefix, domains and expiry date. Never the key itself.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
429rate_limited (minute) or quota_exceeded (UTC day).
Clients
Companies and individuals, prospects and clients. Domain clients.
List clients
GET/clients
Sorted by last update, then by identifier. Cursor pagination: pass nextCursor as cursor to get the next page (null: that was the last one). updatedSince keeps only what changed since that instant, inclusive. Custom fields: cf.<key>=value (text: contains; select, member: equals, comma-separated values: any of them; multi-select: contains any; checkbox: true|false), cf.<key>.min and cf.<key>.max (number, amount, date YYYY-MM-DD, inclusive), cf.<key>.empty=true|false; 400 invalid_filter for an unknown key or an unreadable value.
Permissionclientsread
Parameters
limitintegerquery
Items per page, from 1 to 200 (50 by default).
cursorstringquery
The nextCursor of a previous response, as is (opaque). Unreadable: 400 invalid_cursor.
updatedSincestringquery
ISO 8601 instant in UTC (2026-11-01T00:00:00Z): only what was created or updated since then, inclusive.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
429rate_limited (minute) or quota_exceeded (UTC day).
Create a client
POST/clients
A company (companyName required) or an individual (lastName required), a prospect by default. 409 plan_limit_reached beyond the number of clients included in the plan. customFields: the workspace’s custom fields, by key (GET /custom-fields); every required field needs a value (400 custom_field_invalid, fields: key, label, reason). With an Idempotency-Key header, the same request replayed within 24 hours returns the same response (header Idempotent-Replayed: true) without creating anything again; the same key with a different body: 409 idempotency_key_reused; while the first one is still running: 409 idempotency_key_in_progress.
Permissionclientswrite
Parameters
Idempotency-Keystringheader
Optional, 1 to 255 characters (a UUID, for example), unique to each creation; kept for 24 hours per API key.
Request body ClientInput
A company: companyName required (siren, siret and vatNumber are checked). An individual: lastName required.
typecompany | individualrequired
statusprospect | client
companyNamestring
sirenstring
siretstring
vatNumberstring
websitestring
industrystring
firstNamestring
lastNamestring
addressobject
Postal address. An empty field means null.
address.linestring
The street address.
address.line2string
Additional line: building, locality, PO box.
address.postalCodestring
address.citystring
address.countrystring
ownerIdstring (uuid)
The member in charge: the account of an active member of the workspace; absent: nobody.
originIdstring (uuid)
One of the workspace’s origins; absent: not specified.
customFieldsCustomFieldValues
Custom fields, by key (GET /custom-fields). Only the keys present change, null clears; on creation, every required field needs a value (400 custom_field_invalid).
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
404not_found: not found, or belongs to another workspace.
429rate_limited (minute) or quota_exceeded (UTC day).
Update a client
PATCH/clients/{id}
Only the fields present change; null clears a field (address is replaced as a whole). type never changes; status goes from prospect to client, never the other way round. customFields: only the keys present change, null clears (a required field cannot be cleared).
Permissionclientswrite
Parameters
idstring (uuid)pathrequired
Request body ClientInput
A company: companyName required (siren, siret and vatNumber are checked). An individual: lastName required.
typecompany | individualrequired
statusprospect | client
companyNamestring
sirenstring
siretstring
vatNumberstring
websitestring
industrystring
firstNamestring
lastNamestring
addressobject
Postal address. An empty field means null.
address.linestring
The street address.
address.line2string
Additional line: building, locality, PO box.
address.postalCodestring
address.citystring
address.countrystring
ownerIdstring (uuid)
The member in charge: the account of an active member of the workspace; absent: nobody.
originIdstring (uuid)
One of the workspace’s origins; absent: not specified.
customFieldsCustomFieldValues
Custom fields, by key (GET /custom-fields). Only the keys present change, null clears; on creation, every required field needs a value (400 custom_field_invalid).
423workspace_suspended: the workspace is blocked; it can still be read.
429rate_limited (minute) or quota_exceeded (UTC day).
Delete a client
DELETE/clients/{id}
Its opportunities are deleted with it (WRITE on opportunities is then required), and so are its draft quotes and invoices (WRITE on sales). deleteContacts=true: its contacts are deleted with it; otherwise they remain, without a client.
423workspace_suspended: the workspace is blocked; it can still be read.
429rate_limited (minute) or quota_exceeded (UTC day).
Contacts
Contact records shared with the team. Domain contacts.
List contacts
GET/contacts
clientId keeps only that client’s contacts. Cursor pagination: pass nextCursor as cursor to get the next page (null: that was the last one). updatedSince keeps only what changed since that instant, inclusive. Custom fields: cf.<key>=value (text: contains; select, member: equals, comma-separated values: any of them; multi-select: contains any; checkbox: true|false), cf.<key>.min and cf.<key>.max (number, amount, date YYYY-MM-DD, inclusive), cf.<key>.empty=true|false; 400 invalid_filter for an unknown key or an unreadable value.
Permissioncontactsread
Parameters
clientIdstring (uuid)query
limitintegerquery
Items per page, from 1 to 200 (50 by default).
cursorstringquery
The nextCursor of a previous response, as is (opaque). Unreadable: 400 invalid_cursor.
updatedSincestringquery
ISO 8601 instant in UTC (2026-11-01T00:00:00Z): only what was created or updated since then, inclusive.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
429rate_limited (minute) or quota_exceeded (UTC day).
Create a contact
POST/contacts
A record shared with the team; clientId links it to a client of the workspace. customFields: the workspace’s custom fields, by key (GET /custom-fields); every required field needs a value (400 custom_field_invalid, fields: key, label, reason). With an Idempotency-Key header, the same request replayed within 24 hours returns the same response (header Idempotent-Replayed: true) without creating anything again; the same key with a different body: 409 idempotency_key_reused; while the first one is still running: 409 idempotency_key_in_progress.
Permissioncontactswrite
Parameters
Idempotency-Keystringheader
Optional, 1 to 255 characters (a UUID, for example), unique to each creation; kept for 24 hours per API key.
Request body ContactInput
A contact record, always shared with the team.
firstNamestring
lastNamestringrequired
emailstring (email)
phonestring
jobTitlestring
clientIdstring (uuid)
A client of the workspace to link it to; absent: none.
customFieldsCustomFieldValues
Custom fields, by key (GET /custom-fields). Only the keys present change, null clears; on creation, every required field needs a value (400 custom_field_invalid).
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
404not_found: not found, or belongs to another workspace.
429rate_limited (minute) or quota_exceeded (UTC day).
Update a contact
PATCH/contacts/{id}
Only the fields present change; null clears a field (clientId: the contact is no longer linked to any client). customFields: only the keys present change, null clears (a required field cannot be cleared).
Permissioncontactswrite
Parameters
idstring (uuid)pathrequired
Request body ContactInput
A contact record, always shared with the team.
firstNamestring
lastNamestringrequired
emailstring (email)
phonestring
jobTitlestring
clientIdstring (uuid)
A client of the workspace to link it to; absent: none.
customFieldsCustomFieldValues
Custom fields, by key (GET /custom-fields). Only the keys present change, null clears; on creation, every required field needs a value (400 custom_field_invalid).
423workspace_suspended: the workspace is blocked; it can still be read.
429rate_limited (minute) or quota_exceeded (UTC day).
Opportunities
Deals in progress, won or lost, and sales pipelines. Domain opportunities.
List opportunities
GET/opportunities
clientId and stageId filter. Cursor pagination: pass nextCursor as cursor to get the next page (null: that was the last one). updatedSince keeps only what changed since that instant, inclusive. Custom fields: cf.<key>=value (text: contains; select, member: equals, comma-separated values: any of them; multi-select: contains any; checkbox: true|false), cf.<key>.min and cf.<key>.max (number, amount, date YYYY-MM-DD, inclusive), cf.<key>.empty=true|false; 400 invalid_filter for an unknown key or an unreadable value.
Permissionopportunitiesread
Parameters
clientIdstring (uuid)query
stageIdstring (uuid)query
limitintegerquery
Items per page, from 1 to 200 (50 by default).
cursorstringquery
The nextCursor of a previous response, as is (opaque). Unreadable: 400 invalid_cursor.
updatedSincestringquery
ISO 8601 instant in UTC (2026-11-01T00:00:00Z): only what was created or updated since then, inclusive.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
429rate_limited (minute) or quota_exceeded (UTC day).
Create an opportunity
POST/opportunities
Without stageId or pipelineId: the first open stage of the default pipeline. customFields: the workspace’s custom fields, by key (GET /custom-fields); every required field needs a value (400 custom_field_invalid, fields: key, label, reason). With an Idempotency-Key header, the same request replayed within 24 hours returns the same response (header Idempotent-Replayed: true) without creating anything again; the same key with a different body: 409 idempotency_key_reused; while the first one is still running: 409 idempotency_key_in_progress.
Permissionopportunitieswrite
Parameters
Idempotency-Keystringheader
Optional, 1 to 255 characters (a UUID, for example), unique to each creation; kept for 24 hours per API key.
Request body OpportunityInput
Without stageId or pipelineId: the first open stage of the default pipeline. With pipelineId alone: the first open stage of that pipeline.
clientIdstring (uuid)required
A client of the workspace, prospect or client.
contactIdstring (uuid)
A shared contact of the workspace.
titlestringrequired
amountnumber
pipelineIdstring (uuid)
A pipeline of the workspace (GET /pipelines).
stageIdstring (uuid)
A stage of the workspace (GET /pipelines); won or lost, the deal is closed.
expectedCloseDatestring (date)
ownerIdstring (uuid)
The member in charge: the account of an active member of the workspace; absent: nobody.
customFieldsCustomFieldValues
Custom fields, by key (GET /custom-fields). Only the keys present change, null clears; on creation, every required field needs a value (400 custom_field_invalid).
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
404not_found: not found, or belongs to another workspace.
429rate_limited (minute) or quota_exceeded (UTC day).
Update an opportunity
PATCH/opportunities/{id}
Only the fields present change; null clears a field. stageId moves it (won or lost: closed; won: its prospect becomes a client); pipelineId alone: the first open stage of that pipeline.
Permissionopportunitieswrite
Parameters
idstring (uuid)pathrequired
Request body OpportunityInput
Without stageId or pipelineId: the first open stage of the default pipeline. With pipelineId alone: the first open stage of that pipeline.
clientIdstring (uuid)required
A client of the workspace, prospect or client.
contactIdstring (uuid)
A shared contact of the workspace.
titlestringrequired
amountnumber
pipelineIdstring (uuid)
A pipeline of the workspace (GET /pipelines).
stageIdstring (uuid)
A stage of the workspace (GET /pipelines); won or lost, the deal is closed.
expectedCloseDatestring (date)
ownerIdstring (uuid)
The member in charge: the account of an active member of the workspace; absent: nobody.
customFieldsCustomFieldValues
Custom fields, by key (GET /custom-fields). Only the keys present change, null clears; on creation, every required field needs a value (400 custom_field_invalid).
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
429rate_limited (minute) or quota_exceeded (UTC day).
Tasks
Tasks and follow-ups. Domain tasks.
List tasks
GET/tasks
opportunityId, clientId and done filter. Cursor pagination: pass nextCursor as cursor to get the next page (null: that was the last one). updatedSince keeps only what changed since that instant, inclusive.
Permissiontasksread
Parameters
opportunityIdstring (uuid)query
clientIdstring (uuid)query
donebooleanquery
true: completed tasks; false: tasks still to do; absent: all of them.
limitintegerquery
Items per page, from 1 to 200 (50 by default).
cursorstringquery
The nextCursor of a previous response, as is (opaque). Unreadable: 400 invalid_cursor.
updatedSincestringquery
ISO 8601 instant in UTC (2026-11-01T00:00:00Z): only what was created or updated since then, inclusive.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
429rate_limited (minute) or quota_exceeded (UTC day).
Create a task
POST/tasks
With an opportunity and no client: the opportunity’s client. The assignee is notified as in the app. With an Idempotency-Key header, the same request replayed within 24 hours returns the same response (header Idempotent-Replayed: true) without creating anything again; the same key with a different body: 409 idempotency_key_reused; while the first one is still running: 409 idempotency_key_in_progress.
Permissiontaskswrite
Parameters
Idempotency-Keystringheader
Optional, 1 to 255 characters (a UUID, for example), unique to each creation; kept for 24 hours per API key.
Request body TaskInput
A task. With an opportunity and no client: the opportunity’s client.
titlestringrequired
descriptionstring
dueDatestring (date)
assigneeIdstring (uuid)
The account of an active member of the workspace.
assigneeGroupIdstring (uuid)
Or a group of the workspace (plan with groups), never together with assigneeId.
423workspace_suspended: the workspace is blocked; it can still be read.
429rate_limited (minute) or quota_exceeded (UTC day).
Sales
Quotes and invoices, read-only. Domain sales.
List invoices
GET/invoices
Invoices, deposit invoices and credit notes (type). clientId filters. Cursor pagination: pass nextCursor as cursor to get the next page (null: that was the last one). updatedSince keeps only what changed since that instant, inclusive.
Permissionsalesread
Parameters
clientIdstring (uuid)query
limitintegerquery
Items per page, from 1 to 200 (50 by default).
cursorstringquery
The nextCursor of a previous response, as is (opaque). Unreadable: 400 invalid_cursor.
updatedSincestringquery
ISO 8601 instant in UTC (2026-11-01T00:00:00Z): only what was created or updated since then, inclusive.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
404not_found: not found, or belongs to another workspace.
429rate_limited (minute) or quota_exceeded (UTC day).
Invoice PDF
GET/invoices/{id}/pdf
A presigned link, valid for a few minutes, to the PDF: the frozen Factur-X file for an issued invoice, an up-to-date preview (BROUILLON watermark) for a draft. 503 pdf_not_ready while it is still being generated.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
404not_found: not found, or belongs to another workspace.
429rate_limited (minute) or quota_exceeded (UTC day).
List quotes
GET/quotes
clientId filters. Cursor pagination: pass nextCursor as cursor to get the next page (null: that was the last one). updatedSince keeps only what changed since that instant, inclusive.
Permissionsalesread
Parameters
clientIdstring (uuid)query
limitintegerquery
Items per page, from 1 to 200 (50 by default).
cursorstringquery
The nextCursor of a previous response, as is (opaque). Unreadable: 400 invalid_cursor.
updatedSincestringquery
ISO 8601 instant in UTC (2026-11-01T00:00:00Z): only what was created or updated since then, inclusive.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
404not_found: not found, or belongs to another workspace.
429rate_limited (minute) or quota_exceeded (UTC day).
Quote PDF
GET/quotes/{id}/pdf
A presigned link, valid for a few minutes, to the PDF: frozen for an issued quote, an up-to-date preview (BROUILLON watermark) for a draft. 503 pdf_not_ready while it is still being generated.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
404not_found: not found, or belongs to another workspace.
429rate_limited (minute) or quota_exceeded (UTC day).
Documents
Files stored on client records, read-only. Domain documents.
List documents
GET/documents
clientId filters. Cursor pagination: pass nextCursor as cursor to get the next page (null: that was the last one). updatedSince keeps only what changed since that instant, inclusive.
Permissiondocumentsread
Parameters
clientIdstring (uuid)query
limitintegerquery
Items per page, from 1 to 200 (50 by default).
cursorstringquery
The nextCursor of a previous response, as is (opaque). Unreadable: 400 invalid_cursor.
updatedSincestringquery
ISO 8601 instant in UTC (2026-11-01T00:00:00Z): only what was created or updated since then, inclusive.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
404not_found: not found, or belongs to another workspace.
429rate_limited (minute) or quota_exceeded (UTC day).
Custom fields
Custom fields on clients, contacts and opportunities (read access to the domain of each record type).
List custom fields
GET/custom-fields
The active fields, in order, with their active options. objectType (client, contact or opportunity) requires read access to its domain; without it: the record types the key can read. 403 feature_not_included if the plan does not include custom fields.
401invalid_api_key: key missing, unknown, revoked or expired (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (plan without the API), ip_not_allowed (address outside the workspace’s list).
429rate_limited (minute) or quota_exceeded (UTC day).
Webhooks
Webhooks notify your tools as soon as something happens in Lyane: a client created, an opportunity won, an invoice paid. Instead of polling the API at regular intervals, your server receives a JSON POST request for every event it subscribes to.
They are included in the Enterprise plan, like the public API.
Create a subscription
A workspace administrator opens the app, then Settings → Integrations → Webhooks. They enter the URL that will receive the events and choose which events to send. A workspace can have up to 10 subscriptions.
The URL must use HTTPS and be reachable from the Internet: a private or internal address (local network, localhost, reserved address) is refused. During development, expose your local server through an HTTPS tunnel.
When the subscription is created, the app shows its secret (whsec_…): it is used to verify the signature of every request. Keep it in a secrets manager. The “Send a test” button immediately sends the webhook.test event to the URL.
To change the secret, start a rotation: for 24 hours, every request is signed with both the new and the old secret, giving you time to deploy the new one.
Request body
Every event arrives in the same JSON envelope, whatever its type:
Field
Content
id
The event identifier (evt_…). The same for all its attempts and replays: it is the deduplication key.
type
The event type: client.created, invoice.paid…
createdAt
When the event happened, in ISO 8601 (UTC).
organizationId
The Lyane workspace where it happened.
data
The content of the event.
data.object
The resource concerned, in the same representation as the public API (the one of GET /clients/{id} for a client, for example).
data.previous
Optional, on an update: the changed fields, with their previous values.
For a deletion (*.deleted), data.object only contains the resource identifier: { "id": "…" }. For webhook.test, data.object describes the subscription being tested: id, url and message.
Headers and signature
Every request carries these headers:
Header
Content
Content-Type
application/json.
User-Agent
Lyane-Webhooks/1.0.
Lyane-Webhook-Id
The event identifier, equal to the id field of the body: deduplicate on this value.
Lyane-Webhook-Timestamp
The time of the attempt, in Unix seconds. It changes with every attempt, and so does the signature.
Lyane-Signature
v1= followed by the signature in hexadecimal; two comma-separated values during a secret rotation.
The signature is a hexadecimal HMAC-SHA256. Its key is the whole subscription secret, whsec_ prefix included; its message is the timestamp, a dot, then the raw request body: <Lyane-Webhook-Timestamp>.<body>.
During the 24 hours of a secret rotation, the header carries two signatures, the new one then the old one: v1=<new>,v1=<old>. Accept the request if either one matches.
A complete delivery of the test event:
HTTP
POST /lyane HTTP/1.1
Host: hooks.exemple.fr
Content-Type: application/json
User-Agent: Lyane-Webhooks/1.0
Lyane-Webhook-Id: evt_01JCQ7Z8K9V5W2X3Y4Z5A6B7C8
Lyane-Webhook-Timestamp: 1794477602
Lyane-Signature: v1=89c477430acb503d1ce355b341b864bb96fe3e41fcb43ba7c0fc9138014845c9
{"id":"evt_01JCQ7Z8K9V5W2X3Y4Z5A6B7C8","type":"webhook.test","createdAt":"2026-11-12T10:00:00Z","organizationId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","data":{"object":{"id":"9c4e2a71-1b3d-4f6a-8e2c-5d7f9a0b1c2d","url":"https://hooks.exemple.fr/lyane","message":"Évènement de test envoyé depuis Lyane."}}}
Verify the signature
Before handling a request, check that it really comes from Lyane: compute the signature with your secret, compare it in constant time with each v1= value of Lyane-Signature, and reject a timestamp more than 5 minutes away from your current time, so that an intercepted request cannot be replayed later.
Compute the signature over the raw body, byte for byte, before any parsing: JSON that is parsed and serialized again may not keep the same whitespace or field order, and the signature no longer matches. With Express, read the body with express.raw({ type: 'application/json' }) rather than express.json(); with Flask, with request.get_data().
Node.js
The verification, without any dependency (Node.js 18 or later, in an ES module):
verify-signature.mjs
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 5 * 60;
export function verifyLyaneWebhook({ rawBody, timestamp, signature, secret, now = Date.now() }) {
if (!Buffer.isBuffer(rawBody) && typeof rawBody !== 'string') return false;
if (!secret || !signature || !/^\d+$/.test(timestamp ?? '')) return false;
const age = Math.abs(Math.floor(now / 1000) - Number(timestamp));
if (age > TOLERANCE_SECONDS) return false;
const expected = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest();
// During a secret rotation: "v1=<new>,v1=<old>". One match is enough.
return signature.split(',').some((value) => {
const [version, hex] = value.trim().split('=');
if (version !== 'v1' || !/^[0-9a-f]{64}$/i.test(hex ?? '')) return false;
return timingSafeEqual(Buffer.from(hex, 'hex'), expected);
});
}
An Express server receiving the events, with the secret in the LYANE_WEBHOOK_SECRET environment variable:
server.mjs
import express from 'express';
import { verifyLyaneWebhook } from './verify-signature.mjs';
const app = express();
// Use a database table in production: this set is lost on restart.
const processed = new Set();
app.post('/webhooks/lyane', express.raw({ type: 'application/json' }), (req, res) => {
const valid = verifyLyaneWebhook({
rawBody: req.body,
timestamp: req.get('Lyane-Webhook-Timestamp'),
signature: req.get('Lyane-Signature'),
secret: process.env.LYANE_WEBHOOK_SECRET,
});
if (!valid) return res.sendStatus(401);
const eventId = req.get('Lyane-Webhook-Id');
if (processed.has(eventId)) return res.sendStatus(200);
processed.add(eventId);
const event = JSON.parse(req.body.toString('utf8'));
res.sendStatus(200);
setImmediate(() => handle(event).catch((error) => console.error(eventId, error)));
});
async function handle(event) {
switch (event.type) {
case 'opportunity.won':
console.log('Won:', event.data.object.title);
break;
case 'invoice.paid':
console.log('Paid:', event.data.object.number);
break;
}
}
app.listen(3000);
Python
The verification, with the standard library (Python 3.8 or later):
verify_signature.py
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 5 * 60
def verify_lyane_webhook(raw_body, timestamp, signature, secret, now=None):
if not isinstance(raw_body, bytes) or not secret or not signature:
return False
if not timestamp or not (timestamp.isascii() and timestamp.isdigit()):
return False
current = time.time() if now is None else now
if abs(int(current) - int(timestamp)) > TOLERANCE_SECONDS:
return False
message = timestamp.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
# During a secret rotation: "v1=<new>,v1=<old>". One match is enough.
for value in signature.split(","):
version, _, hex_digest = value.strip().partition("=")
if version == "v1" and hmac.compare_digest(hex_digest.lower().encode(), expected.encode()):
return True
return False
A Flask application receiving the events:
app.py
import json
import os
import queue
import threading
from flask import Flask, request
from verify_signature import verify_lyane_webhook
SECRET = os.environ["LYANE_WEBHOOK_SECRET"]
app = Flask(__name__)
events = queue.Queue()
# Use a database table in production: this set is lost on restart.
processed = set()
@app.post("/webhooks/lyane")
def lyane_webhook():
raw_body = request.get_data()
valid = verify_lyane_webhook(
raw_body,
request.headers.get("Lyane-Webhook-Timestamp", ""),
request.headers.get("Lyane-Signature", ""),
SECRET,
)
if not valid:
return "", 401
event_id = request.headers.get("Lyane-Webhook-Id")
if event_id not in processed:
processed.add(event_id)
events.put(json.loads(raw_body))
return "", 200
def worker():
while True:
event = events.get()
try:
if event["type"] == "opportunity.won":
print("Won:", event["data"]["object"]["title"])
elif event["type"] == "invoice.paid":
print("Paid:", event["data"]["object"]["number"])
except Exception as error:
print(event["id"], error)
threading.Thread(target=worker, daemon=True).start()
To test your code: with the example secret whsec_exemple4f8a2c9e1b7d3f6a5c0e8b2d, the timestamp 1794477602 and the body of the delivery above, the expected signature is v1=89c477430acb503d1ce355b341b864bb96fe3e41fcb43ba7c0fc9138014845c9. Pass this timestamp as the current time (now, in milliseconds in Node.js, in seconds in Python): otherwise the 5-minute tolerance rejects the request.
Retries and deactivation
A delivery succeeds when your server answers with a 2xx status within 10 seconds. Redirects are not followed: a 3xx status counts as a failure, like any other status or no response at all.
After a failure, Lyane retries the same event, with the same Lyane-Webhook-Id. Each delay runs from the previous attempt, except the last one, set 24 h after the first:
Attempt
When
1
As soon as the event happens
2
+1 min
3
+5 min
4
+30 min
5
+2 h
6
+5 h
7
+10 h
8
24 h after the first attempt
When the eighth attempt fails, the subscription is deactivated and the workspace administrators are notified by email.
The app keeps the delivery history of each subscription for 30 days. Its “Replay” button sends an event again, with its original identifier.
Best practices
Answer quickly, then process: verify the signature, put the event in a queue, answer 200, and do the work afterwards. Long processing goes over the 10 seconds and triggers a new attempt.
Deduplicate on Lyane-Webhook-Id: the same event can arrive more than once (a lost response, a replay). Keep the identifiers already handled in a table, not only in memory.
Make processing idempotent: applying the same event twice must leave the same result. Write the state you received (“the invoice is paid”) rather than an increment.
Do not rely on ordering: two events can arrive out of order, especially after a retry. Compare createdAt, or read the resource again with the public API when in doubt.
opportunity.stage_changed is sent on every stage change, including to won or lost, in addition to opportunity.won or opportunity.lost: subscribe to one or the other depending on what you track.
Keep the secret server-side, and reject any request whose signature does not match (401).
Event reference
Every event, grouped by domain, with a complete body example. This list is generated from the OpenAPI specification (webhooks section).