Edara API v3: Guide

Read this page before any reference page. It covers how to call the API and the behaviours that most often cause wrong results. Last verified against the live API on 2026-09-28.

Hosts

https://api.edara.io is the separate v2 API (/v2.0/...). It has a different response format. Do not mix the two.

Authentication

Send the token in the Authorization header. Two kinds of token work:

• Integration token. Create it in Edara under Data, then Integration, then Rest APIs. The value you copy already starts with Bearer, so send it as is.
• A signed-in user's Edara access token (JWT). Send it as Bearer <token> and add the TenantId header with the organization's id.

GET /v3/customers?offset=0&limit=100 HTTP/1.1
Host: edara-api.edara.io
Authorization: Bearer <token>
TenantId: <organization id>      # only with a user JWT
Accept-Language: ar              # optional: localizes error detail text
Content-Type: application/json

Each endpoint requires one permission, shown on its reference entry (for example read:customer). A 403 response names the missing permission in detail.

Request and response format

• JSON only. Property names are camelCase.
• Enums are sent and returned as names ("Confirmed"), not numbers.
• Ids are integers. Requests refer to other records by id (customerId, warehouseId). To look up by code, use the explicit code/{code} routes.
• Responses embed related records as reference objects: { "id": 1, "code": "...", "name": "..." }.
• Null values are included in responses.
• A successful create returns 201 with a Location header and the created object.

Paging

{ "items": [], "totalCount": 142, "page": 2, "pageSize": 100, "totalPages": 2 }

• offset defaults to 0. limit defaults to 100 and the maximum is 1000.
• Use offsets that are multiples of limit.
• Some endpoints reject a limit outside 1 to 1000 with a 400. Others silently fall back to 100. Each reference table says which.
• A few endpoints have a different cap, and a few are not paged at all. Check the endpoint.
• Always loop until offset >= totalCount. Do not stop because a page came back short.

Errors

Errors use application/problem+json:

{ "title": "Conflict", "status": 409, "detail": "localized text",
  "instance": "/v3/brands", "traceId": "...", "errorCode": "DupplicatedName",
  "errors": { "name": ["..."] } }

• Match on errorCode, never on detail. The detail text is localized.
• Error codes keep their original spelling: DupplicatedName and DupplicatedCode have a double p.
• PhantomRead (409) means the record changed while you were editing it. Reload and retry.
• Batch endpoints return 200 with { "succeeded": [], "failed": { "<key>": "message" } }. Partial success is normal, so always inspect failed.

Rate limits

• 5 requests per second, 250 per minute and 5,500 per hour.
• A limit can apply per user or per organization, so several integrations in one organization can share one budget. Leave room for the others.
• Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Scope. The scope names the limit closest to being reached.
• On 429, wait for the number of seconds in Retry-After. Do not send large parallel bursts.

Behaviours that cause wrong results

Filters that are on by default

Send these explicitly. If you omit them, results shrink without any error.

• GET /v3/sales-orders: onlyMyOrders defaults to true, which returns only orders the calling user created. warehouseOnly defaults to true, which leaves out sales-store (point of sale) orders. Sales returns appear in the same list.
• GET /v3/work-orders: onlyMyOrders defaults to true, including for code and paperNumber lookups. To find one document reliably, query with false, then with true, and remove duplicates by id.
• GET /v3/journal-entries and GET /v3/accounts/{id}/balance: isPostedOnly defaults to true. Journal entries created through the API are saved unposted, so they do not appear until they are posted.

Matching differs per endpoint

Never assume items[0] is the record you asked for.

• GET /v3/customers: code, name, phone, mobile and email match partially. externalId matches exactly. updateDate returns records changed strictly after the value. search behaves differently: active customers only, at most 50 matches per field.
• GET /v3/stock-items: only one filter applies per call, in this order: code, sku, partNumber, externalId. A filtered call ignores offset and limit and returns every match. The unfiltered list returns 404 when there are no items. Inactive items are included.
• GET /v3/stock-items/search: returns at most 1000 items, in no guaranteed order, with no totalCount. Inactive items are left out.

An empty list can mean missing data permissions

Lists of warehouses, customers, stock items and sales orders are filtered by the calling user's data permissions in Edara. A user without them gets an empty 200, not a 403. If a list is unexpectedly empty, check that user's data permissions first.

Date range filters

Most ...To filters compare a full date and time. dateTo=2026-09-22 means midnight at the start of that day, so the whole day is left out. Send 2026-09-22T23:59:59.997.

Slow calls

• GET /v3/warehouses/{id}/balance and GET /v3/sales-orders are slow on large data. Do not use them to copy data in bulk.
• For balances, prefer GET /v3/warehouses/stock-items-balances or GET /v3/stock-items/warehouse-summary (limit up to 5000).

Writing data

• PUT replaces the whole record. Fields you omit are cleared or reset. For example, a tax update without active deactivates the tax. Always GET the record, change it, then PUT it.
• Unknown ids in a create or update often return 400 without an errorCode, or sometimes 500, instead of 404. Validate ids before you write.
• Exchange rate. If you omit it on a work order, it is 1, even for a foreign currency. On a journal entry, it is today's rate, not the rate on the document date. More than 6 decimals is refused with 409 ExchangeRateDecimalsExceedLimit.
• Always send externalId when you create a sales order. A retry with the same externalId is refused with a 400 that has no errorCode. Treat that as "already created" and look the order up. Without externalId, a retry creates a duplicate.
• Sales-order line prices are not filled in from the item. A missing price becomes 0, which is refused unless the organization allows zero prices.
• Sales-order status calls do not check the current status. Issue, un-issue and status updates change the status only, and issue does not create a stock issue or an invoice. Enforce the allowed transitions in your own code.
• Confirm deletes. After deleting or deactivating a stock item, read it again to confirm. A 204 does not always mean the item changed.

Known response issues

• GET /v3/stock-items/serials returns serialNumber as null.
• GET /v3/sales-orders/brand-sales with an unknown brand name returns all brands.
• Items in GET /v3/customers carry balance: 0. Use GET /v3/customers/{id}/balance.

Shared shapes

• PagedResult<T>: see Paging.
• BatchResult: { "succeeded": [], "failed": {} }, see Errors.
• ProblemDetails: see Errors.
• *Reference (for example CustomerReference, WarehouseReference): { id, code, name }.