API v2 gives programs access to the Elbuz catalog, price lists, customers, documents, deals and organizer with one employee's permissions: a request sees and changes exactly what that employee can. By default, changes await approval in Pulse.
When you need this:
- Your website needs prices and stock: changed products are read by cursor, without gaps.
- Website orders must reach Elbuz: retrying after a dropped connection creates no duplicate.
- A contractor edits data: each change arrives in Pulse as “before → after”.
- An integration shouldn't see everything: the key gets its employee's windows, fields and “Data scope”.
Where to start: create a key in the “API & access tokens” window.
What API v2 can do
- Read lists with filters and a cursor — products, price list rows, customers, documents, deals, tasks, emails, calls.
- Create and change records — as a request in Pulse or right away, as the key allows.
- Run actions — post a document, merge duplicates, start a price list import or an export.
- Avoid duplicates when a request is retried after a dropped connection.
- Limit access with the employee's permissions — the key has no separate settings for that.
- Notify you about changes with webhooks, so you don't have to poll the every minute.
How to create a key and what it sees
- In the “API & access tokens” window, click “+”. The new key's card opens.
- In the “On behalf of” field, choose whose permissions the key gets. The employee list is visible only to users with access to the users window; everyone else can create a key only for themselves.
- The “User” field is the key name. It appears in the titles of Pulse requests (“Key “site_sync”: change product…”), so name the key to make clear whose integration it is.
- A new key is created with “Read only” checked. If the integration needs to change anything, clear it.
- Click “Create key” and copy the value from the “New key” field with the “Copy” button.
1
On behalf of2
Data changes3
Safety limit: changes per hour4
Current key5
Read only- On behalf of — whose permissions and data the key gets. Other employees are visible only to someone with access to the users window.
- Data changes — “Ask” (every change waits in Pulse) or “Do it myself”. Only “Management” can switch it.
- Safety limit — after this many executed changes per hour the key returns to “Ask” on its own.
- The new key is shown once: copy it with the Copy button before closing the window.
- Read only — on for a new key; clear it if the key needs to change something.
The key is shown only once. The database stores only its fingerprint (SHA-256) and the first eight characters after elbz_ — they help you recognize the key in the list (“elbz_6caef5fd_…”). Lost it? Click “Create a new key”: the old one stops working that same second, so update it in the integration at once.
The other card fields apply to every request, without reissuing the key: clear “Active” and the next request gets 401; “Access end date” — the key works through this date inclusive; “Allowed IP addresses” — a list separated by commas, spaces or new lines; empty means from anywhere.
What the key sees
A request runs as if the employee had opened the matching window. So:
- A resource is available if the employee can open its window: products — the products window, documents — any of the document windows. No window — no resource, neither in the description nor in lists (404).
- A field hidden from the employee's group (for example, “Cost price”
price_cost) is missing from the response entirely, and you can't filter by it. A field the group may not change gives 422 on write:errorsshows the reason next to the field; for a product, “Editing this field is not allowed”. - “Data scope” works just as in the window: a manager with “Own only” gets only their own customers and documents; someone else's record by id — 404.
- Window buttons: creating, deleting and posting a document are checked against the permissions for the matching buttons.
The key has no separate “scopes”. To narrow an integration, create the key for an employee with narrower permissions — for example, add a user in a department that can open only the orders window.
First request and response format
curl -s "https://<your-domain>/api/v2/products?limit=2&fields=product_id,name,price,quantity" \
-H "Authorization: Bearer elbz_xxxxxxxx_…"
Response (demo account, 14.10.2026):
{"data":[
{"product_id":1,"price":"4536","quantity":100,"name":"Marshall Willen Black and Brass (1006059)"},
{"product_id":2,"price":"0","quantity":0,"name":"ADATA 16 GB DDR4 3600 MHz XPG Spectrix D41 RGB Tungsten Gray (AX4U360016G18I-ST41)"}],
"has_more":true,
"next_cursor":"eyJrIjoiMiIsImgiOiJiZTExNWY1MSJ9"}
The format is the same for all resources: a list is {"data":[…],"has_more":…,"next_cursor":…}, a single record is {"data":{…}}. Values come as follows:
- ids, links to other records, quantities and counters — as numbers;
- flags such as
flag_export—true/false; - money and measurements — as a decimal string (
"4536"); - external codes (
sku,uuid, barcodes) — as strings; - dates — in RFC 3339 format with a time zone offset (
"2026-10-14T12:42:59+02:00").
The fields= parameter works both for a list and for a single record (GET /products/2?fields=product_id,sku,price). The Accept-Language: uk header switches the language of field names in the resource description.
The full description of all resources, fields and methods is GET /api/v2/openapi.json (OpenAPI 3.1) with the same key; without a key — 401. It is built for the key owner's permissions: resources and fields the employee can't see aren't in it. A short summary is GET /api/v2/: for each resource, its operations, actions and fields marked filter, sort, write.
Reading lists: filters, sorting, cursor
| Parameter | What it does |
|---|---|
limit | page size, 50 by default, 200 at most |
fields=product_id,name | keep only these list fields in the response |
filter[field]=value | equals |
filter[field][operator]=value | operators ne, gt, gte, lt, lte, like (contains) |
filter[updated_since]=2026-10-01 | changed since a date — same as filter[date_modified][gte] |
sort=-quantity | sorting by one field; a minus means descending. A second field after a comma is ignored |
q= | quick text search (products) |
cursor= | the next_cursor value from the previous page |
You can filter and sort only by fields marked filter / sort in the resource description. An unknown field gives 400 with an explanation: {"errors":{"nosuch":"not filterable"}}.
How the cursor works. Without sort, records come in ascending id order and the cursor remembers the last id: records added while you page through don't shift the pages. With sort, the cursor remembers the page number, and a record whose sort position changes meanwhile may appear twice or be skipped. For syncing, go without sort.
The cursor is tied to the request's filters and sorting: change them and pass the old cursor, and you get 400 cursor does not match the query. The end of the list is "has_more":false and "next_cursor":null.
Reference lists (currencies, warehouses, document_statuses and others) are returned in full, up to 500 rows, without a cursor. Document rows come only together with the document: GET /api/v2/document_items?filter[document_id]=123; without the filter — 400.
curl -s -g "https://<your-domain>/api/v2/products?filter[quantity][gt]=5&fields=product_id,name,quantity&limit=100" \
-H "Authorization: Bearer elbz_…"
What happens to a change request
| Request | What it does |
|---|---|
POST /api/v2/{resource} | create a record |
PATCH /api/v2/{resource}/{id} | change the fields you send (the rest stay untouched) |
DELETE /api/v2/{resource}/{id} | move to Trash — only where the resource has a Trash |
POST /api/v2/{resource}/{id}/{action} | an action: post a document, merge duplicates, run an export, and so on |
What happens to the request is decided by the “Data changes” field in the key card.
“Ask (via Pulse)” is the default. Elbuz checks the request against the key owner's permissions (resource, field, button, “Data scope”) and, if all is well, changes nothing but puts a request in Pulse. The integration gets 202 Accepted and an address to track the decision:
HTTP/1.1 202 Accepted
Location: /api/v2/approvals/3629
{"data":{"status":"pending","approval_id":3629}}
The request is visible to employees with access to the API keys window: the key name, what it wants to do, and the old and new value of each field.
GET /api/v2/approvals/3629 returns status: pending — waiting; approved — accepted and done (result holds the record after the change); auto — done without a person in “Act on its own” mode; rejected — nothing changed; error — accepted but failed; undone — undone in “Done by AI”. A key sees only its own requests.
“Act on its own” — the change runs at once: creating returns 201 with a Location header, editing returns 200 with the record after the change (both also include approval_id), deleting returns 204 with no body.
Each change is still logged in Pulse with the “Done by AI” status and shown on the “Done by AI” tab, where you can undo it. Only Management can turn on “Act on its own”.
Safety limit. If a key in “Act on its own” has made as many changes within an hour as set in “Safety limit: changes per hour” (500 by default), the next change doesn't run: the key switches itself to “Ask”, and Pulse shows the proposal “Key “…” made N changes within an hour and was paused — continue without confirmation?”.
Until it is accepted, all the key's changes go as requests (202).
Regardless of the key mode: a reply to a customer email (/mail_messages/{id}/reply) and a chat message (/chats/{id}/send) become their own type of Pulse request, like emails written by the Elbuz AI. They wait for a person until Management turns on “Act on its own” for that type on the “Trust” tab and the AI “Controller” lets the email through.
- A “Read only” key gets 403 on any write.
- A key changes its own webhook subscriptions itself, without requests.
- Start or end
- Action or result
- Decision: the path depends on the answer
What can be undone
The undo button in “Done by AI” is available for: field edits on any resource (restores the previous values), creating and deleting a contact, document, deal, task, note, project or article (via Trash), posting and unposting, and marking a task done.
A field edit can't be undone if those fields were changed again after the API call — the answer is “undo it manually”. There is no button for creating a product, category, manufacturer, attribute, attribute group, contact group or follow-up (they have no Trash), for merging duplicates, moving a deal to a stage, or starting background jobs.
Avoiding duplicates: Idempotency-Key
Every POST (creates and actions) requires an Idempotency-Key header: any unique string up to 255 characters, such as a . Without it: 400. The response is kept for 24 hours: a retry with the same key and body creates no duplicate and returns the saved response with Idempotent-Replayed: true. The same key with a different body — 422.
curl -s -X POST "https://<your-domain>/api/v2/contractors" \
-H "Authorization: Bearer elbz_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-sync-2026-10-14-0001" \
-d '{"name":"API Test LLC","email":"test-api@example.com"}'
An error response (400, 422) is also stored under this key. Fixed the body? Use a new Idempotency-Key, or you'll get 422 “Idempotency-Key was used with another request”. Only 429 and server errors are not stored.
Errors and limits
Errors come in RFC 9457 format (application/problem+json) with the real HTTP code:
{"type":"https://elbuz.com/problems/unprocessable","title":"Unprocessable","status":422,
"detail":"some fields cannot be written","errors":{"date_modified":"not writable"}}
| Code | type | When |
|---|---|---|
| 400 | bad_request | no Idempotency-Key, the body isn't a JSON object, a filter on an unknown field, a cursor from another query |
| 401 | unauthorized | no header; the key is wrong, disabled or expired; the owner employee is inactive |
| 403 | forbidden | the address isn't in “Allowed IP addresses”, a “Read only” key, no permission for the button |
| 404 | not_found | the resource doesn't exist or its window is closed, the record is outside “Data scope” |
| 405 | method_not_allowed | the resource has no such operation — for example, DELETE /products/2 |
| 409 | conflict | such a record already exists (for example, a contact with the same details) — its id is in errors |
| 422 | unprocessable | a field can't be written, a link to a record you can't see, a repeated Idempotency-Key with a different body |
| 429 | rate_limited | request limit exceeded |
Every response has an X-Request-Id header — give it to support, and they'll find the request in the log.
The limit is 120 requests per rolling minute per key (more only if support raised it for this key); MCP assistant requests with the same key count toward the same limit. The remainder is in each response's headers: RateLimit-Policy: "default";q=120;w=60 and RateLimit: "default";r=119;t=60 (r: requests left, t: seconds until reset). A 429 comes with Retry-After: wait that many seconds.
Why 422 after PATCH when some fields are already saved
For products, manufacturers, contacts, documents and deals, fields are written one by one, the same way as editing a cell in the window grid; for other resources, in a single save call. A field missing from the resource description, a system field or one closed by permissions is rejected before anything is written — 422 with the list of fields.
But if, on a resource with per-field editing, one field is rejected by the app's own check (an invalid value, or the group may not change the field — “Editing this field is not allowed”), the response is also 422, yet the other fields from that request are already saved: re-read the record with GET before retrying.
Available resources
The set below is for an employee with full access; a key gets only those whose windows its owner can open.
| Resource | Operations | Actions |
|---|---|---|
products | list, record, create, edit | — |
categories, manufacturers | list, record, create, edit | merge |
attributes | list, record, create | merge |
attribute_groups | list, record, create | — |
supplier_products (price list rows) | list, record | — |
contractors | all; delete — to Trash | merge |
companies, contractor_groups | list, record (groups also create and edit) | — |
documents (+ document_items) | all; delete — to Trash | sign, unsign |
orders (customer orders) | list, record | POST /orders/sync — your store's orders in batches of up to 100: create new ones and update imported ones, details |
deals, pipelines | deals — all, delete to Trash; pipelines — list | move_stage |
tasks, notes, projects | all; delete — to Trash | done, reopen |
touches (calendar follow-ups) | list, record, create, edit | — |
mail_messages, chats, chat_messages, calls | read only | reply, send — always via Pulse |
pulse_items | list, record | accept, reject, accept_trust, undo |
users | read only, without passwords or sign-in keys | — |
articles | all; delete — to Trash | — |
price_lists, export_templates, flows | list, record | import / run — background job |
import_templates, jobs, sales_report | read only | — |
webhooks, webhook_deliveries | this key's webhooks | — |
reference lists: document_types, document_statuses, payment_statuses, delivery_statuses, payment_types, delivery_types, stock_statuses, warehouses, stores, currencies, languages | read only, as a whole list | — |
Actions with a background job (/price_lists/{id}/import, /export_templates/{id}/run, /flows/{id}/run) return {"data":{"status":"queued","job_id":…}}; in “Ask” mode — first 202 and a request in Pulse. Progress: GET /api/v2/jobs/{id}. Aggregates (“orders by status”, “sales total by manager”): GET /api/v2/query?spec={…}; entities and fields: ?spec={"describe":true}.
Document items: product by product_id or by name
Document items are passed to POST /api/v2/documents in the item_list array. An item with no product_id but with a name is saved too — Elbuz finds a product for it:
- first by the
eanbarcode, then by thesku, then by exact name. Names are compared ignoring case, extra spaces and quotes, and match only if the database has exactly one product with that name; - if nothing is found, it creates a new product with the item's name, SKU, barcode and price in the service category “Products - api_v2 - …”. A document created by the MCP assistant or the in-browser AI agent without Pulse approval puts new products in “Products - mcp - …” or “Products - ai - …”. The category is created disabled and excluded from exports.
A document never has items without a product: an item with neither product_id nor name isn't saved. A product_id that doesn't exist or that the key can't see gives 422 before the document is created, with "item_list.0.product_id": "not found" in errors (the number is the item's position in the array).
curl -s -X POST "https://<your-domain>/api/v2/documents" \
-H "Authorization: Bearer elbz_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{"type_id":3,"contractor_id":15,"item_list":[
{"product_id":2,"quantity":1,"price":"1890"},
{"name":"HDMI 2.1 cable, 2 m","sku":"HDMI-21-2M","ean":"4820000000017","quantity":3,"price":"250"}]}'
To avoid piling up products, pass product_id in the item (GET /products returns it), and if you don't have it, at least ean or sku, exactly as in the Elbuz product card. Matching by name works only on an exact, unique match: a different name in the order or two same-named products create a new card.
New cards collect in the “Products - api_v2 - …” service categories: check them to spot items Elbuz didn't recognize.
Scenarios
Your website pulls stock and prices
A “Read only” key on behalf of an employee who can open only the products window. Every 10 minutes — GET /products?filter[updated_since]=…&fields=product_id,sku,price,quantity without sort, paging with the cursor. The purchase price won't get into the response if its field is hidden from this employee's group.
Website orders without duplicates
A key in “Act on its own” mode on behalf of a sales manager. The website sends new and changed orders in a batch to POST /orders/sync: Elbuz recognizes an already imported order by its website number and updates payment, delivery and status without overwriting the manager's status. Format and rules: store orders via the API.
A contractor edits descriptions and you review them
A key in “Ask” mode on behalf of an employee with access to the products window. Each PATCH arrives in Pulse as a line “Full description: … → …”. If the edits are good — “Accept all from this key”; if you trust it — “Accept and do it yourself from now on”.
What to do when a request fails
| What you see | Why | What to do |
|---|---|---|
| 401 “invalid, disabled or expired key” | the key was reissued, “Active” was cleared, or the end date has passed | check the key card (create a key) |
| PATCH returns 202, but the data hasn't changed | the key is in “Ask” mode | accept the request in Pulse or switch the key (changes) |
| 403 “read-only key” | a new key has “Read only” checked | clear the checkbox in the key card |
| A field visible in the window is missing from the response | the field is hidden from the key owner's group | open the field in group permissions or create the key for another employee |
| 422 “Idempotency-Key was used with another request” | the same idempotency key with a different body | a new Idempotency-Key (details) |
| 400 “cursor does not match the query” | a cursor from a request with other filters | start paging again without cursor |
FAQ
Can I give a key access to orders only?
Yes: create the key on behalf of an employee who can open only the orders window. The key gets the permissions of that one employee — windows, fields and “Data scope”.
Why does a change via the API return 202?
The key is in “Ask” mode: the change is waiting for approval in Pulse. Status: GET /api/v2/approvals/{id}. To make changes right away, Management switches the key to “Act on its own”.
How many requests per minute are allowed?
120 per rolling minute per key, including MCP requests with the same key. The remainder is in the RateLimit header; a 429 comes with Retry-After.
Where is the description of all methods?
GET https://<your-domain>/api/v2/openapi.json with the key in the header. The description is built for the key owner's permissions.
Can I delete a product via the API?
No. Via the API, only contacts, documents, deals, tasks, notes, projects and articles can be moved to Trash. Duplicate contacts, categories, manufacturers and attributes are merged with the merge action.
Can I write several records in one request?
Only orders: POST /orders/sync accepts up to 100 orders per request. Other records take one request each; plan your volume around 120 requests per minute.
Does the old api_token work with v2?
No. api_token and the api/login sign-in work only with the old API. How to move your integration: migrating to v2.
Where it is and who has access
- Menu
- Account → System settings → “Other settings” → the “API & access tokens” tile
- API address
https://<your-domain>/api/v2/- Access right
- the “API & access tokens” window; to create a key for another employee, also access to the users window
- “Act on its own” mode
- only Management can turn it on
- Prepare
- an employee with the permissions the integration should get
Related topics
- If Claude, ChatGPT or Cursor should read your data — connect an AI assistant via MCP with the same key.
- If you don't want to poll the API every minute — API v2 webhooks.
- If your integration still uses
api/login— the old API v1 and migrating to v2. - If the key can't see the fields it needs — users and permissions.
- If the key has many requests in Pulse — Pulse: accept, trust, undo.
