# Search unit of measure groups

Operation ID: `searchUnitOfMeasureGroups`

Group: Inventory › Unit of Measure Groups

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/searchUnitOfMeasureGroups)

`POST /inventory/unit-of-measure-groups/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches unit of measure groups. The filters are name, a unit of measure the group converts, and when the group last changed. Each group comes back whole, with its base unit and conversion lines.

Only this endpoint can find the groups that convert a given unit of measure, with filters.unitOfMeasureId.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Request body

Required, `application/json`: searchUnitOfMeasureGroupsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A unit of measure group must match every filter you send. Send an empty object to return all unit of measure groups. Example: `{"unitOfMeasureId":"8c1f4a72-6b09-4d15-a3e7-40d2b6915cf8"}`. |
| `filters.name` | string | no | Limits results to unit of measure groups with this name. The match is exact. Names are not unique, so this may match several groups. |
| `filters.unitOfMeasureId` | string | no | Limits results to unit of measure groups with a conversion line for this unit of measure, including groups where it is the base unit. See id on GET inventory/unit-of-measures/:id. |
| `filters.modifiedSince` | date-time | no | Limits results to unit of measure groups changed on or after this time. Format YYYY-MM-DDTHH:mm:ss.sssZ. Adding, changing or removing a conversion line counts as a change to the group. |
| `page` | object | no | The pagination controls. Omit for the first page. Example: `{"size":50}`. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit for the first page. |
| `page.size` | number | no | The number of unit of measure groups per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```json
{
  "filters": {
    "unitOfMeasureId": "8c1f4a72-6b09-4d15-a3e7-40d2b6915cf8"
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchUnitOfMeasureGroupsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The unit of measure groups on this page, ordered by id. An empty array when nothing matches. Example: `[{"id":"2c7e5a91-6d38-4b04-8f72-1e9c03d5b846","name":"Packaging","description":"Eaches, boxes and pallets","baseUnitOfMeasureId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","baseUnitCode":"EA","lines":[{"id":"9f1b60d4-27ac-4e53-b8f1-05d3e79a2c68","unitOfMeasureId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","unitCode":"EA","unitName":"Each","conversionFactor":"1.00","isBaseUnit":true},{"id":"e04a83f5-91c6-4d27-a5b0-73f2e618d94c","unitOfMeasureId":"8c1f4a72-6b09-4d15-a3e7-40d2b6915cf8","unitCode":"BOX","unitName":"Box","conversionFactor":"12.00","isBaseUnit":false}],"lastModifiedDate":"2026-08-03T11:15:00.000Z"}]`. |
| `items[].id` | string | yes | The unique identifier for the unit of measure group. |
| `items[].name` | string | yes | The display name of the unit of measure group. Names are not unique. |
| `items[].description` | string | no | A free-form description of what the group covers. Absent when none was given. |
| `items[].baseUnitOfMeasureId` | string | no | The unique identifier for the base unit of measure that every conversion factor in the group is relative to. Absent when the group has no lines. See id on GET inventory/unit-of-measures/:id. |
| `items[].baseUnitCode` | string | no | The code of the base unit of measure. Absent when the group has no lines. |
| `items[].lines` | array<object> | yes | The group's conversion lines, ordered by line id. An empty array when the group has none. |
| `items[].lines[].id` | string | yes | The unique identifier for the conversion line. This is what updateLines and deleteLines address on PATCH inventory/unit-of-measure-groups/:id, not the unit. |
| `items[].lines[].unitOfMeasureId` | string | yes | The unique identifier for the unit of measure this line converts. See id on GET inventory/unit-of-measures/:id. |
| `items[].lines[].unitCode` | string | yes | The code of that unit of measure. |
| `items[].lines[].unitName` | string | yes | The display name of that unit of measure. |
| `items[].lines[].conversionFactor` | decimal | yes | How many base units of measure make up one of this unit. It is always greater than zero, and 1 on the base unit's own line. |
| `items[].lines[].isBaseUnit` | boolean | yes | Whether this line is for the group's own base unit of measure. Exactly one line has it, and its conversionFactor is 1. |
| `items[].lastModifiedDate` | date-time | no | The date and time the unit of measure group or its conversion lines last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `pagination` | object | yes | The pagination cursor for this page. Example: `{"hasMore":false}`. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | True when more unit of measure groups remain beyond this page. |

```json
{
  "data": {
    "items": [
      {
        "id": "2c7e5a91-6d38-4b04-8f72-1e9c03d5b846",
        "name": "Packaging",
        "description": "Eaches, boxes and pallets",
        "baseUnitOfMeasureId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
        "baseUnitCode": "EA",
        "lines": [
          {
            "id": "9f1b60d4-27ac-4e53-b8f1-05d3e79a2c68",
            "unitOfMeasureId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
            "unitCode": "EA",
            "unitName": "Each",
            "conversionFactor": "1.00",
            "isBaseUnit": true
          },
          {
            "id": "e04a83f5-91c6-4d27-a5b0-73f2e618d94c",
            "unitOfMeasureId": "8c1f4a72-6b09-4d15-a3e7-40d2b6915cf8",
            "unitCode": "BOX",
            "unitName": "Box",
            "conversionFactor": "12.00",
            "isBaseUnit": false
          }
        ],
        "lastModifiedDate": "2026-08-03T11:15:00.000Z"
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error