---
title: "Lookup assets by a field"
method: POST
path: "/assets/v1/assets:LookupAssetsByField"
tags: ["Assets"]
---

# Lookup assets by a field

`POST /assets/v1/assets:LookupAssetsByField`

## Request body

- S12AssetsV1LookupAssetsByFieldRequest — The parameters for `LookupAssetsByField`
  - `page_token` string — OPTIONAL. The value of next_page_token from a previous response. If specified, the API will return the next batch of results following the previous list assets request.
  - `page_size` integer — OPTIONAL. The number of assets to return. By default, each request returns 50 assets. You can specify a page_size value between 1 to 100.
  - `asset_filters` S12AssetsV1AssetFilter[] — OPTIONAL. The array of asset filters to apply in your request. You can apply multiple filters in a single request.
    - `site_id` string — The unique identifier of the assigned site to filter by.
    - `state` 'ASSET_STATE_UNSPECIFIED' | 'ASSET_STATE_ACTIVE' | 'ASSET_STATE_ARCHIVED' — Describes the state of an asset. Either active or archived. - ASSET_STATE_UNSPECIFIED: Indicates that an asset state is unspecified. - ASSET_STATE_ACTIVE: Indicates that an asset is active. - ASSET_STATE_ARCHIVED: Indicates that an asset is archived.
    - `type_id` string — The unique identifier of the asset type to filter by.
    - `asset_id` string — The unique identifier of the asset to filter by.
    - `asset_code` string — The user-defined unique identifier id of the asset to filter by.
    - `motion_status` 'LOCATION_MOTION_STATUS_UNSPECIFIED' | 'LOCATION_MOTION_STATUS_PARKED' | 'LOCATION_MOTION_STATUS_IDLING' | 'LOCATION_MOTION_STATUS_MOVING' | 'LOCATION_MOTION_STATUS_OFFLINE' — Status of the motion. - LOCATION_MOTION_STATUS_UNSPECIFIED: Indicates the status of the motion is unspecified. - LOCATION_MOTION_STATUS_PARKED: Indicates the status of the motion is parked. - LOCATION_MOTION_STATUS_IDLING: Indicates the status of the motion is idling. - LOCATION_MOTION_STATUS_MOVING: Indicates the status of the motion is moving. - LOCATION_MOTION_STATUS_OFFLINE: Indicates the offline status of the telematic device
    - `location_source` 'ASSET_LOCATION_SOURCE_UNSPECIFIED' | 'ASSET_LOCATION_SOURCE_INSPECTION' | 'ASSET_LOCATION_SOURCE_GEO' | 'ASSET_LOCATION_SOURCE_MOBILE_DEVICE' — Describes the source of asset location. - ASSET_LOCATION_SOURCE_UNSPECIFIED: Indicates that the source of asset location is unspecified. - ASSET_LOCATION_SOURCE_INSPECTION: Indicates that the source of asset location is inspection. - ASSET_LOCATION_SOURCE_GEO: Indicates that the source is GEO location. - ASSET_LOCATION_SOURCE_MOBILE_DEVICE: Indicates that the source is mobile device location.
  - `order_by` S12AssetsV1AssetsOrderBy — Describes the sorting options for the list assets endpoint. By default, assets are sorted by creation date from the most recent to the least recent.
    - `sort_field` 'SORT_FIELD_UNSPECIFIED' | 'SORT_FIELD_CREATED_AT' | 'SORT_FIELD_MODIFIED_AT' | 'SORT_FIELD_CODE' | 'SORT_FIELD_ASSET_FIELD' | 'SORT_FIELD_INSPECTED_AT' | 'SORT_FIELD_STATUS_OPTION_NAME' — Defaults to SORT_FIELD_CODE. - SORT_FIELD_UNSPECIFIED: The sort field is unspecified. - SORT_FIELD_CREATED_AT: Sort assets by `created_at`. - SORT_FIELD_MODIFIED_AT: Sort assets by `modified_at`. - SORT_FIELD_CODE: Sort assets by `code`. - SORT_FIELD_ASSET_FIELD: Sort assets by an asset-field. - SORT_FIELD_INSPECTED_AT: Sort assets by `inspected_at`. - SORT_FIELD_STATUS_OPTION_NAME: Sort assets by status option name (alphabetical).
    - `sort_direction` 'SORT_DIRECTION_UNSPECIFIED' | 'SORT_DIRECTION_ASC' | 'SORT_DIRECTION_DESC'
    - `field_id` string — Field_id is required while sorting by an asset-field i.e., When SortField = SORT_FIELD_ASSET_FIELD.
  - `field_name` string, required — REQUIRED. The name of the asset field to match.
  - `string_value` string — REQUIRED. The string value of the asset field to match.

## Response `200`

A successful response.

- S12AssetsV1LookupAssetsByFieldResponse — Result returned from `LookupAssetsByField`
  - `assets` S12AssetsV1Asset[] — The assets found from your request contained in an array as objects.
    - `id` string, required — The unique identifier of an asset. This ID is system-generated.
    - `code` string — The user-defined unique identifier of an asset. This ID is user-generated.
    - `type` S12AssetsV1AssetType — Asset type entity.
      - `name` string — Name of the type.
      - `type_id` string — The global unique identifier of the type.
      - `type` 'TYPE_CATEGORY_UNSPECIFIED' | 'TYPE_CATEGORY_PREDEFINED' | 'TYPE_CATEGORY_CUSTOM' — Category of Type. - TYPE_CATEGORY_UNSPECIFIED: Type Category Unspecified. - TYPE_CATEGORY_PREDEFINED: Predefined Type defined by system. - TYPE_CATEGORY_CUSTOM: Custom type defined by organisation.
    - `fields` S12AssetsV1AssetField[] — The associated fields of an asset contained in an array. Each asset's fields are based on its asset type. Please make sure the asset fields you use associated with the specified asset type. You can retrieve the associated fields using the list type and field association endpoint.
      - `name` string — The name of an asset field.
      - `string_value` string — The string value of an asset field. This attribute is only used for asset fields using the FIELD_VALUE_TYPE_STRING type.
      - `money_value` S12CommonMoney — Represents an amount of money with its currency type.
        - `currency_code` string — The 3-letter currency code defined in ISO 4217.
        - `units` string, int64 — The whole units of the amount. For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar.
        - `nanos` integer — Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example £-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.
      - `timestamp_value` string, date-time — The timestamp value of an asset field. This attribute is only used for asset fields using the FIELD_VALUE_TYPE_TIMESTAMP type.
      - `field_id` string — The unique identifier of an asset field. This ID is system-generated.
    - `media` S12CommonMedia[] — All the media directly uploaded to an asset.
      - `id` string
      - `token` string
      - `filename` string — full file name, including file extension
      - `media_type` 'MEDIA_TYPE_IMAGE' | 'MEDIA_TYPE_VIDEO' | 'MEDIA_TYPE_PDF' | 'MEDIA_TYPE_DOCX' | 'MEDIA_TYPE_XLSX' | 'MEDIA_TYPE_PPTX' | 'MEDIA_TYPE_CSV' — - MEDIA_TYPE_IMAGE: An image file (GIF, JPG, PNG, WEBP). - MEDIA_TYPE_VIDEO: A video file (MP4, MOV). - MEDIA_TYPE_PDF: A PDF document. - MEDIA_TYPE_DOCX: A Microsoft Word document (DOCX, DOC). - MEDIA_TYPE_XLSX: A Microsoft Excel spreadsheet (XLSX, XLS). - MEDIA_TYPE_PPTX: A Microsoft PowerPoint presentation (PPTX, PPT). - MEDIA_TYPE_CSV: A CSV file.
    - `created_at` string, date-time — The date created timestamp of an asset.
    - `modified_at` string, date-time — The date last modified timetstamp of an asset.
    - `site` S12AssetsV1AssetSite — Describes the values of a site that's assigned to an asset.
      - `id` string — The unique identifier of a site. This ID is system-generated.
      - `name` string — The name of a site.
    - `profile_image` S12CommonMedia
      - `id` string
      - `token` string
      - `filename` string — full file name, including file extension
      - `media_type` 'MEDIA_TYPE_IMAGE' | 'MEDIA_TYPE_VIDEO' | 'MEDIA_TYPE_PDF' | 'MEDIA_TYPE_DOCX' | 'MEDIA_TYPE_XLSX' | 'MEDIA_TYPE_PPTX' | 'MEDIA_TYPE_CSV' — - MEDIA_TYPE_IMAGE: An image file (GIF, JPG, PNG, WEBP). - MEDIA_TYPE_VIDEO: A video file (MP4, MOV). - MEDIA_TYPE_PDF: A PDF document. - MEDIA_TYPE_DOCX: A Microsoft Word document (DOCX, DOC). - MEDIA_TYPE_XLSX: A Microsoft Excel spreadsheet (XLSX, XLS). - MEDIA_TYPE_PPTX: A Microsoft PowerPoint presentation (PPTX, PPT). - MEDIA_TYPE_CSV: A CSV file.
    - `state` 'ASSET_STATE_UNSPECIFIED' | 'ASSET_STATE_ACTIVE' | 'ASSET_STATE_ARCHIVED' — Describes the state of an asset. Either active or archived. - ASSET_STATE_UNSPECIFIED: Indicates that an asset state is unspecified. - ASSET_STATE_ACTIVE: Indicates that an asset is active. - ASSET_STATE_ARCHIVED: Indicates that an asset is archived.
    - `inspected_at` string, date-time — The date last modified inspection of an asset.
    - `sourced_from_external_system` boolean — @deprecated. Use GetAsset API to get the sourced_from_external_system Indicates if an asset is sourced from an external system.
    - `statuses` S12AssetsV1AssetStatus[] — The status assigned to the asset. Although this is a repeated field, only one entry is currently supported. Each entry must belong to the status group associated with the asset type.
      - `status_option_id` string — ID of the assigned status option.
      - `name` string — Name of the status option.
      - `status_group_id` string — ID of the status group the option belongs to.
      - `color` 'STATUS_BADGE_COLOR_ACCENT' | 'STATUS_BADGE_COLOR_INFO' | 'STATUS_BADGE_COLOR_NEGATIVE' | 'STATUS_BADGE_COLOR_POSITIVE' | 'STATUS_BADGE_COLOR_WARNING' | 'STATUS_BADGE_COLOR_SURFACE' — StatusBadgeColor defines the semantic color palette for status badges. - STATUS_BADGE_COLOR_ACCENT: Color is accent - STATUS_BADGE_COLOR_INFO: Color is info - STATUS_BADGE_COLOR_NEGATIVE: Color is negative - STATUS_BADGE_COLOR_POSITIVE: Color is positive - STATUS_BADGE_COLOR_WARNING: Color is warning - STATUS_BADGE_COLOR_SURFACE: Color is surface
      - `status_group_name` string — Name of the status group the option belongs to.
  - `next_page_token` string — The value you can use to retrieve additional assets. If a value exists, it means there are more results than listed. Use the value in your request body as a page_token field to view more results.

## Other responses

- `default` — An unexpected error response.

---

[API](https://skmtc.net/safetyculture/apis/safetyculture-api.md) · [All operations](https://skmtc.net/safetyculture/apis/safetyculture-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/safetyculture/safetyculture-api/revisions/5be91df61ded/schema)