Reading data in bulk

Guidance for connectors, warehouse loads and any scheduled sync.

Search endpoints are POST

The highest-volume collections are read with POST, not GET, because their filter sets are too large for a query string. The search criteria go in the request body. These are reads and they create nothing.

POST /assets/searches         assets
POST /workorders/searches     work orders
POST /vendors/{companyId}     vendors, where the path segment is your company id

Paging

Page with QuerySkip and QueryTake. On the POST search endpoints they are properties in the request body. On the GET collections they are query-string parameters. Casing does not matter in either position.

{ "QuerySkip": 0, "QueryTake": 1000 }

GET /employees?queryskip=0&querytake=1000

Page by holding QueryTake steady and advancing QuerySkip by that amount each time, until a response comes back with fewer rows than you asked for. 1,000 is a sensible page size.

Each endpoint applies a fixed sort before paging: work orders by work order number, assets by asset tag number, employees by employee id, location audits by audit date. The first three are unique, so pages never overlap or skip. Audit dates are not unique, so records sharing a date can move between pages.

Omitting QueryTake does not mean a sensible default

Endpoint                    Paging        If you omit QueryTake
--------------------------  ------------  ------------------------------------------
POST /workorders/searches   body          Capped at 4,000 rows
POST /assets/searches       body          Returns EVERY matching asset, no cap
GET  /employees             query string  Returns all matching employees
GET  /locationaudits        query string  Returns all matching audits
GET  /locations             none          Returns every location (small list)
GET  /workorders/reasons    none          Returns every reason (small list)
GET  /lists/enums           none          Returns every enum value (small list)

POST /assets/searches has no server-side cap. Omit QueryTake and you will pull every asset the company has in a single response. Always set it.

Syncing only what changed

Work orders are the only high-volume collection that can be filtered by modification time. Send UpdatedOnDate in the body of POST /workorders/searches to get the work orders modified on that date.

UpdatedOnDate selects a single day, not a starting point. The time portion of the value you send is discarded, and the filter matches one UTC calendar day. There is no changed-since filter. A nightly job that pulls yesterday works naturally; to backfill a range, loop one request per day.

Assets cannot be filtered by date modified. POST /assets/searches accepts install-date range, location, category, subcategory, manufacturer, asset type, status, tag number and serial number among others, but nothing equivalent to UpdatedOnDate. Plan on a full refresh for assets.

Everything else, locations, vendors, work order reasons and enums, is small enough that a full refresh each run is the right approach.

What has no read endpoint

Parts can be created through the API but not listed or read. If you need parts data in a warehouse, contact support@startwoven.com so we can scope it.

Getting changes pushed to you instead of polling

Woven can call your endpoint when specific events occur, which is often a better fit than a scheduled pull. Webhooks are managed through this API. You will need the company id you authenticated as, which comes back on your login response.

List your webhooks     GET    /companies/{companyId}/companywebhooks
Register a new one     POST   /companies/{companyId}/companywebhooks
Read one               GET    /companies/{companyId}/companywebhooks/{webhookId}
Update one             PUT    /companies/{companyId}/companywebhooks/{webhookId}
Remove one             DELETE /companies/{companyId}/companywebhooks/{webhookId}
Subscribe to an event  POST   /companies/{companyId}/companywebhooks/{webhookId}/triggers
Unsubscribe            DELETE /companies/{companyId}/companywebhooks/{webhookId}/triggers/{trigger}
Delivery history       GET    /companies/{companyId}/companywebhooks/{webhookId}/logs
One delivery           GET    /companies/{companyId}/companywebhooks/{webhookId}/logs/{txnId}

Registering a webhook is two steps. First create the webhook, which requires a Name and the destination Url. Then add a trigger for each event you want to receive. A webhook with no triggers is never called, so the second step is not optional.

Available triggers cover work orders (created, closed, reopened, reassigned, state changed, note added, document added, asset added), assets (retired, relocated, status active, status inactive, metered usage reset) and training (course completed, practical completed). There is no general record-edited trigger, so webhooks complement a periodic full refresh rather than replacing it.

The delivery logs are the first place to look when an expected notification does not arrive.