↑↓ selectEnter openEsc close

    1. Elbuz

    API v2: a key on behalf of an employee, lists, changes and errors

    12 min readUpdated

    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

    1. In the “API & access tokens” window, click “+”. The new key's card opens.
    2. 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.
    3. 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.
    4. A new key is created with “Read only” checked. If the integration needs to change anything, clear it.
    5. Click “Create key” and copy the value from the “New key” field with the “Copy” button.
    API v2 key card: on behalf of an employee, data changes mode, safety limit and the new key
    1On behalf of
    2Data changes
    3Safety limit: changes per hour
    4Current key
    5Read only
    1. On behalf of — whose permissions and data the key gets. Other employees are visible only to someone with access to the users window.
    2. Data changes — “Ask” (every change waits in Pulse) or “Do it myself”. Only “Management” can switch it.
    3. Safety limit — after this many executed changes per hour the key returns to “Ask” on its own.
    4. The new key is shown once: copy it with the Copy button before closing the window.
    5. 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: errors shows 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

    ParameterWhat it does
    limitpage size, 50 by default, 200 at most
    fields=product_id,namekeep only these list fields in the response
    filter[field]=valueequals
    filter[field][operator]=valueoperators ne, gt, gte, lt, lte, like (contains)
    filter[updated_since]=2026-10-01changed since a date — same as filter[date_modified][gte]
    sort=-quantitysorting 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

    RequestWhat 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.
    Path of a change request: the permission check always runs; then the key mode decides whether to run it now or create a request
    yesnonoyesyesnoAskAct on its ownyesnoPOST, PATCH or DELETE request“Read only” key?403, nothing changedDo the key owner's permissionsallow it?403, 404 or 422 with the reasonEmail or message to a customer?Request in Pulse, response 202Key modeHourly safety limit reached?Key switches to “Ask”, Pulse offersto continueDone at once: 200, 201 or 204,logged in “Done by AI”
    • 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"}}
    CodetypeWhen
    400bad_requestno Idempotency-Key, the body isn't a JSON object, a filter on an unknown field, a cursor from another query
    401unauthorizedno header; the key is wrong, disabled or expired; the owner employee is inactive
    403forbiddenthe address isn't in “Allowed IP addresses”, a “Read only” key, no permission for the button
    404not_foundthe resource doesn't exist or its window is closed, the record is outside “Data scope”
    405method_not_allowedthe resource has no such operation — for example, DELETE /products/2
    409conflictsuch a record already exists (for example, a contact with the same details) — its id is in errors
    422unprocessablea field can't be written, a link to a record you can't see, a repeated Idempotency-Key with a different body
    429rate_limitedrequest 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.

    ResourceOperationsActions
    productslist, record, create, edit—
    categories, manufacturerslist, record, create, editmerge
    attributeslist, record, createmerge
    attribute_groupslist, record, create—
    supplier_products (price list rows)list, record—
    contractorsall; delete — to Trashmerge
    companies, contractor_groupslist, record (groups also create and edit)—
    documents (+ document_items)all; delete — to Trashsign, unsign
    orders (customer orders)list, recordPOST /orders/sync — your store's orders in batches of up to 100: create new ones and update imported ones, details
    deals, pipelinesdeals — all, delete to Trash; pipelines — listmove_stage
    tasks, notes, projectsall; delete — to Trashdone, reopen
    touches (calendar follow-ups)list, record, create, edit—
    mail_messages, chats, chat_messages, callsread onlyreply, send — always via Pulse
    pulse_itemslist, recordaccept, reject, accept_trust, undo
    usersread only, without passwords or sign-in keys—
    articlesall; delete — to Trash—
    price_lists, export_templates, flowslist, recordimport / run — background job
    import_templates, jobs, sales_reportread only—
    webhooks, webhook_deliveriesthis key's webhooks—
    reference lists: document_types, document_statuses, payment_statuses, delivery_statuses, payment_types, delivery_types, stock_statuses, warehouses, stores, currencies, languagesread 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 ean barcode, then by the sku, 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

    Common problems
    What you seeWhyWhat to do
    401 “invalid, disabled or expired key”the key was reissued, “Active” was cleared, or the end date has passedcheck the key card (create a key)
    PATCH returns 202, but the data hasn't changedthe key is in “Ask” modeaccept the request in Pulse or switch the key (changes)
    403 “read-only key”a new key has “Read only” checkedclear the checkbox in the key card
    A field visible in the window is missing from the responsethe field is hidden from the key owner's groupopen 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 bodya new Idempotency-Key (details)
    400 “cursor does not match the query”a cursor from a request with other filtersstart 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

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free