For the complete documentation index, see llms.txt. This page is also available as Markdown.

Search for service-orders across the tenant

Search every service order of the tenant. A caller holding SERVICE_ORDER at any level — tenant-wide, at an organization or at any one store — reaches every service order of the tenant here, whichever store owns it and whichever store took it in. This is the search the workspace runs: it is what the service order counts endpoint counts over, and what a saved list opens, so a dashboard card's number and the list behind it always agree. The request is the same as the store-scoped search and behaves the same way — case insensitive, partial values match, the array fields work like filters, and query searches customer, service number and title in one, ignoring the separate customer and service fields when it is used. There is no store in the path here, so storeUids in the body is the only filter on the owning store: name stores in it to narrow to them, and leave it out to search the whole tenant. storeUids and createdFromStoreUids narrow within the tenant, and a store the caller holds no permission at narrows like any other: naming it is not refused, and it matches the service orders that store owns in storeUids and the ones it took in in createdFromStoreUids. A storeUid naming no store of the tenant at all answers 400. What the results leave out: secrets and checklistAnswers are always empty arrays, and formValues leaves out the values captured for sensitive fields. Read the one service order to see them: the checklist answers at any store of the tenant, the secrets and the sensitive values at the store that owns it or the store it was taken in at. Sensitive values take no part in the matching either, so a sensitive serial can be neither read out of a result nor probed for here. Every service order of the tenant matches wherever it sits, so a case a store took in and has since sent on is found as surely as one it still holds. A store's view of what it took in is this search with createdFromStoreUids naming that store: everything it registered, wherever it sits now. Add storeUids naming the stores those cases went to and what is left is what that store sent there; the two compose, so a saved list holding both is exactly what one store sent to another, and a list holding createdFromStoreUids alone is everything it ever took in.

Required permissions: SERVICE_ORDER

post
/tenants/{tenantUid}/serviceorders/search
Authorizations
AuthorizationstringRequired

Access token recevied after user login with a deviceToken

Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
Query parameters
pageNumberintegerOptional

Reference to a specific page in a result set.

pageSizeintegerOptional

The number of items per page in a result set.

sortBystringOptional

Defines which field the resource list is sorted by.

sortDirectionstring · enumOptional
ENUMDescription
ASCSort in ascending order
DESCSort in descending order
Possible values:
Body
customerNamestringOptional
customerMobilestringOptional

Filter by the start of the customer's mobile number. Whitespace in it is ignored, and the number is matched the way query matches a whole number against the mobile number, without the five-digit minimum. A customerMobile of whitespace alone is no filter, and one that is not a whole number once its whitespace is taken out, or is zeros alone, matches no case. It is ignored when query carries a word.

customerEmailstringOptional
titlestringOptional
serviceNumberstringOptional
querystringOptional

Search on the customer, the service number and the title in one. The query is split on whitespace into words, and every word must match at least one of the service number, the title, or the customer's first name, last name or e-mail, partially and case-insensitively — so a customer's full name in either order, or a name word together with a title word, finds the case. A word that is a whole number — digits, with an optional leading + — of at least five digits also matches the start of the customer's mobile number, typed as the national number with or without its leading 0, or with the tenant's country code after a +, after 00 or after nothing: in a tenant whose country's phonePrefix is +47, 91234567, 4791234567, 004791234567 and +4791234567 all find the cases of the customer whose mobile is +4791234567, and in a +46 tenant 0701234567 finds +46701234567. Its leading zeros are taken off a number of at least eight digits only; a shorter number that begins with 0 is matched as typed. A number written with a + and its country code finds a mobile of any country. A whole number of fewer than five digits never matches the mobile number, and neither does one of zeros alone. A query that is a whole number once its whitespace is taken out is read as that one number, so a number typed in groups, +47 912 34 567 or 912 34 567, is read whole; beside a word the groups are not joined, and in ola 912 34 567 each group is a word of its own. A query that is one whole number alone matches only the service number and, under the rule above, the start of the customer's mobile number. A query of whitespace alone is no query. It does not match externalSalesOrderNumber or externalServiceNumber, which are filters of their own. When query carries a word, customerName, customerEmail, customerMobile, serviceNumber and title are ignored.

fromCreatedDatestring · dateOptional

GTE date, e.g. 2006-05-04

toCreatedDatestring · dateOptional

LTE date, e.g. 2006-05-04

assignedUserUidsstring[]Optional

Filter by who the service order is held by. The entries are user uids, and an empty string entry means held by the store and assigned to nobody — the same thing an empty assignedUserUid says on the service order itself. A service order matches when it is held by any one of the listed entries, so "mine and the ones up for grabs" is one list with two entries: the user's own uid and an empty string. The list is OR within itself and AND with the other filters, exactly as every other list filter here is.

createdFromStoreUidsstring[]Optional

Filter by the store a service order was taken in at. It never changes, so it still names the counter a case was registered at long after the case has moved on. This is not storeUids, which filters on the store that owns it today; the two differ for the rest of a case's life once it has been moved. Wherever the request runs without a store in the path, this is how a store lists everything it took in, wherever those cases sit now — the ones it still owns and the ones it has sent on alike. Narrow it with storeUids to say where they sit: naming the store itself leaves what it still owns, and naming another store leaves what it sent there.

openbooleanOptional

Set to true to get only the service orders that are still open: the ones that have not finished, whatever state they are on. Which states end a service order is ServiceStateENUM's own business — COMPLETE and CANCELLED as it stands — and a service order that is reopened is open again. The filter only ever applies when it is true. Leaving it out, or sending false, does not filter on this at all: it never means "only the finished ones", which is what serviceStates and the finished-date filters are for. It narrows like every other filter, so sending it beside serviceStates asks for both at once: a request that names only the states which end a service order in serviceStates, and sends open true, matches nothing. Ask with it rather than by listing the states a client believes to be open — ServiceStateENUM is extensible, and a state added later falls on the right side of this filter from the moment it exists, here, in the service order counts endpoint and in every saved list holding these filters.

serviceTypeUidsstring[]Optional
storeUidsstring[]Optional

Filter by the store that owns the service order — the store the work sits with and where the customer collects it. This is not createdFromStoreUids, which filters on the store that took the service order in; the two differ whenever a service order has been moved between stores. How it composes with the store in the path: on the store-scoped search the path store scopes the result, and storeUids narrows within it — naming a store the path store does not cover matches nothing. Wherever the same request shape runs without a store in the path — on the tenant-level search, the counts endpoint and the filters a saved list holds — the reach is every service order of the tenant, and storeUids is the only filter on the owning store there is: it narrows within the tenant. Naming a store the caller holds nothing at is not refused: it matches the service orders that store owns. storeUids narrows on the store that owns a service order alone. A case a store took in and has since sent on is outside a storeUids naming that store, because another store owns it now; createdFromStoreUids is the filter that names it.

serviceStatusUidsstring[]Optional

Filter by the status the service order is on now.

fromReadyAtNeededstring · date-timeOptionalDeprecated

Deprecated. The service module follows one date, readyAtEstimate — filter on fromReadyAtEstimate instead. It is ignored when sent. It will be removed after the announced deprecation window; see the deprecation log for the date.

toReadyAtNeededstring · date-timeOptionalDeprecated

Deprecated. The service module follows one date, readyAtEstimate — filter on toReadyAtEstimate instead. It is ignored when sent. It will be removed after the announced deprecation window; see the deprecation log for the date.

fromReadyAtEstimatestring · date-timeOptional

GTE date-time on readyAtEstimate, the point in time the work on the service order is estimated to be ready. The bound is inclusive: a whole-day "from" bound is that day's first millisecond, 00:00:00.000 in the tenant's timezone. Service orders with no readyAtEstimate are left out when this is used.

toReadyAtEstimatestring · date-timeOptional

LTE date-time on readyAtEstimate, the point in time the work on the service order is estimated to be ready. The bound is inclusive: a whole-day "to" bound is that day's last millisecond, 23:59:59.999 in the tenant's timezone, so a value saved at 23:59:59.999 is inside it, as is the end of that day with no time picked. Service orders with no readyAtEstimate are left out when this is used.

overduebooleanOptional

Set to true to get only the service orders that are running late. A service order is late when its readyAtEstimate is in the past and it is neither a finished service order nor on a status of the state READY_FOR_PICKUP, where its work is ready and waits only for the customer; a service order with no readyAtEstimate is never late. The filter only ever applies when it is true. Leaving it out, or sending false, does not filter on lateness at all: it never means "only the ones on time".

serialstringOptional

Filter by serial number or IMEI. Matches the serial number and IMEI values captured on the service order's intake form as well as the serial numbers on its items — both the parts that were installed and the parts that were removed. Case insensitive, and partial values match. Values captured for a field marked sensitive never take part in the matching. A sensitive serial can therefore be neither read out of a result nor probed for by guessing at it here: search is no way around the sensitivity of a field.

serviceJobTypeUidsstring[]Optional

Filter by the job types the work on the service order consists of. A service order matches when it carries any one of the listed job types.

externalServiceNumberstringOptional

Filter by externalServiceNumber: the number an outside workshop or supplier handling the work gives the case. Case insensitive, and partial values match.

claimNumberstringOptional

Filter by claimNumber: the number the insurer gave the claim on an insurance case. Case insensitive, and partial values match.

externalSalesOrderNumberstringOptional

Filter by externalSalesOrderNumber: the order number, in the tenant's external order system, of the sales order the unit was bought on — never the service number. Case insensitive, and partial values match. Leading and trailing whitespace is trimmed, and a value of spaces alone is no filter.

customerNumberstringOptional

Filter by the customer number of the customer on the service order. Case insensitive, and partial values match.

customerUidsstring[]Optional

Filter to the service orders that belong to these customers. A service order matches when it is on any one of the listed customers. This is also how a customer page the tenant builds itself asks for one customer's service orders, through an integration token.

productUidsstring[]Optional

Filter by the product the unit in for service is — the model of the machine on the bench, not the parts on the service order's items. A service order matches when the unit it is about is any one of the listed products. This is how "every one of this model we have had in" is asked for.

fromFinishedDatestring · dateOptional

GTE date on the date the service order last reached a terminal state, COMPLETE or CANCELLED, e.g. 2006-05-04. Service orders that are not finished are left out when this is used, however long they have been open — and a reopened service order is not finished until it ends again. This is what the workspace tiles count through: "completed today", "completed the last 7 days" and "completed the last 30 days" put a date on this filter and narrow serviceStates to COMPLETE, counted by the service order counts endpoint.

toFinishedDatestring · dateOptional

LTE date on the date the service order last reached a terminal state, COMPLETE or CANCELLED, e.g. 2006-05-04. Service orders that are not finished are left out when this is used, however long they have been open — and a reopened service order is not finished until it ends again. This is what the workspace tiles count through: "completed today", "completed the last 7 days" and "completed the last 30 days" put a date on this filter and narrow serviceStates to COMPLETE, counted by the service order counts endpoint.

Responses
200

Example response

application/json
post/tenants/{tenantUid}/serviceorders/search
POST /v2/tenants/{tenantUid}/serviceorders/search HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 850

{
  "customerName": "text",
  "customerMobile": "text",
  "customerEmail": "text",
  "title": "text",
  "serviceNumber": "text",
  "query": "text",
  "fromCreatedDate": "2026-01-01",
  "toCreatedDate": "2026-01-01",
  "assignedUserUids": [
    "text"
  ],
  "createdFromStoreUids": [
    "text"
  ],
  "priorities": [
    "HIGHEST"
  ],
  "serviceStates": [
    "AWAITING_PRODUCT"
  ],
  "open": true,
  "serviceTypeUids": [
    "text"
  ],
  "storeUids": [
    "text"
  ],
  "serviceStatusUids": [
    "text"
  ],
  "fromReadyAtEstimate": "2026-01-01T00:00:00.000Z",
  "toReadyAtEstimate": "2026-01-01T00:00:00.000Z",
  "overdue": true,
  "serial": "text",
  "serviceJobTypeUids": [
    "text"
  ],
  "externalServiceNumber": "text",
  "claimNumber": "text",
  "externalSalesOrderNumber": "text",
  "customerNumber": "text",
  "customerUids": [
    "text"
  ],
  "productUids": [
    "text"
  ],
  "coverages": [
    "PAYABLE"
  ],
  "fromFinishedDate": "2026-01-01",
  "toFinishedDate": "2026-01-01",
  "formValueFilters": [
    {
      "fieldKey": "text",
      "value": "text"
    }
  ]
}
200

Example response

{
  "items": [
    {
      "serviceOrderUid": "text",
      "tenantUid": "text",
      "storeUid": "text",
      "orderProductLineUid": "text",
      "orderUid": "text",
      "customerUid": "text",
      "customerName": "text",
      "createdFromStoreUid": "text",
      "assignedUserUid": "text",
      "assignedUserDisplayName": "text",
      "serviceTypeUid": "text",
      "serviceTypeName": "text",
      "serviceStatusUid": "text",
      "serviceStatusName": "text",
      "serviceState": "AWAITING_PRODUCT",
      "title": "text",
      "serviceNumber": "text",
      "externalServiceNumber": "text",
      "externalSalesOrderNumber": "text",
      "description": "text",
      "priority": "HIGHEST",
      "estimatedPrice": 1,
      "maxPrice": 1,
      "readyAtEstimate": "2026-01-01T00:00:00.000Z",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "text",
      "lastModifiedAt": "2026-01-01T00:00:00.000Z",
      "lastModifiedBy": "text",
      "totals": {
        "goodsTotal": 1,
        "grandTotal": 1,
        "otherTotal": 1
      },
      "items": [
        {
          "serviceOrderItemUid": "text",
          "serviceOrderUid": "text",
          "warehouseUid": "text",
          "warehouseName": "text",
          "tenantUserUid": "text",
          "productUid": "text",
          "salesOrderUid": "text",
          "quantity": 1,
          "name": "text",
          "sku": "text",
          "coverImage": {
            "productMediaUid": "text",
            "mainUrl": "text",
            "thumbnailUrl": "text"
          },
          "priceOverride": true,
          "price": 1,
          "costPrice": 1,
          "originalPrice": 1,
          "discountReasonCode": "text",
          "discountReference": "text",
          "totalPrice": 1,
          "totalCostPrice": 1,
          "serialNumber": "text",
          "removedSerialNumber": "text",
          "note": "text",
          "orderItemReferenceValue": "text",
          "tenantUserDisplayName": "text",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "createdBy": "text",
          "lastModifiedAt": "2026-01-01T00:00:00.000Z",
          "lastModifiedBy": "text"
        }
      ],
      "assets": [
        {
          "assetUid": "text",
          "name": "text",
          "description": "text",
          "isPublic": true,
          "customerVisible": true,
          "publicUrl": "text",
          "mimeType": "text",
          "size": "text",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "createdBy": "text",
          "tenantUserUid": "text",
          "tenantUserDisplayName": "text"
        }
      ],
      "rmaOrderItemUid": "text",
      "rmaOrderUid": "text",
      "formValues": [
        {
          "serviceFormFieldUid": "text",
          "fieldKey": "text",
          "label": "text",
          "fieldType": "TEXT",
          "systemKind": "SERIAL_NUMBER",
          "sensitive": true,
          "value": "text",
          "values": [
            "text"
          ],
          "redacted": true
        }
      ],
      "intakeFormUid": "text",
      "secrets": [
        {
          "secretUid": "text",
          "serviceOrderUid": "text",
          "label": "text",
          "serviceFormFieldUid": "text",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "createdBy": "text"
        }
      ],
      "serviceJobTypes": [
        {
          "serviceJobTypeUid": "text",
          "name": "text"
        }
      ],
      "checklistAnswers": [
        {
          "serviceJobTypeUid": "text",
          "item": "text",
          "checked": true,
          "tenantUserUid": "text",
          "tenantUserDisplayName": "text",
          "screenAccountTenantUserUid": "text",
          "answeredAt": "2026-01-01T00:00:00.000Z"
        }
      ],
      "quotedPrice": 1,
      "quoteState": "NONE",
      "termsText": "text",
      "termsUrl": "text",
      "termsAccepted": true,
      "coverage": "PAYABLE",
      "productUid": "text",
      "insuranceCompanyCustomerUid": "text",
      "deductible": 1,
      "claimNumber": "text"
    }
  ],
  "paging": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalCount": 1
  }
}

Last updated

Was this helpful?