Skip to main content

Programmatic Search for Authentication Items

searchAuthenticationItems searches the logged-in user's authentications, one page at a time. Use it to build your own history list. Each item can be passed to displayDetailViewForItem or to fetchSessionDetails.

Overview​

searchAuthenticationItems supports:

  • Date range filtering: the last N days, or a custom start and end.
  • Filters: by status, category, brand and flag.
  • Pagination: cursor based, one page per call.
  • Result mode: full results, or only the counts.

Method Signature​

fun searchAuthenticationItems(
query: EntrupySearchQuery,
callback: SearchAuthenticationItemsCallback,
)

The user must be logged in. The query is read when the method is called, so changing it afterwards does not affect a search that is already running.

Building a Search Query​

EntrupySearchQuery (com.entrupy.sdk.model) holds every search parameter. Create one and set what you need.

import com.entrupy.sdk.model.EntrupySearchFilter
import com.entrupy.sdk.model.EntrupySearchQuery

val query = EntrupySearchQuery().apply {
dateRange = EntrupySearchQuery.DateRange.Last(90)
filters = listOf(
EntrupySearchFilter.Status(listOf(EntrupySearchFilter.AuthenticationStatus.Authentic)),
EntrupySearchFilter.Category(listOf(EntrupySearchFilter.ItemCategory.Luxury)),
)
limit = 10
}

Query Properties​

PropertyTypeDefaultDescription
dateRangeDateRange?DateRange.Last(30)When the items were created. null searches without a date range
filtersList<EntrupySearchFilter>emptyThe filters to apply
resultModeEntrupySearchResultModeResultsFull results, or only the counts
limitInt20The maximum number of items per page. Must be greater than 0
cursorList<String>?nullWhere the page starts. null for the first page

The filter values are sealed classes. Each one has an Other(value) case, so you can send a value that is newer than your SDK version:

EntrupySearchFilter.Status(listOf(EntrupySearchFilter.AuthenticationStatus.Other("new_status")))

Date Range​

EntrupySearchQuery.DateRange.Last(days = 7)
EntrupySearchQuery.DateRange.Custom(
start = "2026-01-01T00:00:00Z",
end = "2026-01-31T23:59:59Z",
)

Last takes 0 or more days. Custom takes ISO 8601 date-times with a time zone, without fractional seconds. As on iOS, a value that cannot be read searches without a date range.

Result Mode​

ValueDescription
EntrupySearchResultMode.ResultsReturns the items of the page
EntrupySearchResultMode.CountOnlyReturns only totalCount. The items list is empty
EntrupySearchResultMode.Other(value)A mode your SDK version does not name, sent and read as is

Applying Filters​

Filters are combined with AND. The values inside one filter are combined with OR.

For example, items that are (authentic or under review) and in the luxury category:

query.filters = listOf(
EntrupySearchFilter.Status(
listOf(
EntrupySearchFilter.AuthenticationStatus.Authentic,
EntrupySearchFilter.AuthenticationStatus.UnderReview,
)
),
EntrupySearchFilter.Category(listOf(EntrupySearchFilter.ItemCategory.Luxury)),
)

Status​

EntrupySearchFilter.Status(statuses), with EntrupySearchFilter.AuthenticationStatus values:

ValueDescription
AuthenticItem is authentic
UnderReviewEntrupy is still reviewing the item
InvalidInvalid submission
NotSupportedItem type not supported
UnidentifiedAuthenticity could not be determined
Other(value)Any other status value

Items matched by Unidentified come back with the result status EntrupyResultStatusId.UNKNOWN.

Category​

EntrupySearchFilter.Category(categories), with EntrupySearchFilter.ItemCategory values Luxury, Apparel, Sneakers and Other(value).

Category filter is optional

Without a category filter, or with one that has no categories, the search covers every category. This differs from iOS, where the query must include a category filter.

Brands​

EntrupySearchFilter.Brands(brandIds) takes brand IDs:

EntrupySearchFilter.Brands(listOf("louis_vuitton", "chanel"))

Flag​

EntrupySearchFilter.Flag(flags), with EntrupySearchFilter.FlagStatus values:

ValueDescription
NoneNo flag applied
FlaggedCurrently flagged
ResolvedThe flag has been resolved
Other(value)Any other flag value

Pagination​

Load the first page with cursor = null. To load the next page, set cursor to the previous result's nextCursor and search again. A null nextCursor means it was the last page.

import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.listeners.SearchAuthenticationItemsCallback
import com.entrupy.sdk.model.EntrupySearchItemsResult
import com.entrupy.sdk.model.EntrupySearchQuery

class HistoryLoader {
private val query = EntrupySearchQuery()

fun loadNextPage() {
EntrupyApp.sharedInstance().searchAuthenticationItems(
query = query,
callback = object : SearchAuthenticationItemsCallback {
override fun onSearchCompleted(result: EntrupySearchItemsResult) {
showRows(result.items)
query.cursor = result.nextCursor
if (result.nextCursor == null) showEndOfList()
}

override fun onSearchError(errorCode: Int, description: String) {
showError(errorCode, description)
}
},
)
}
}

Only ask for the next page after the previous one answered. Two pages asked at once would both start from the same cursor.

Count Only​

val query = EntrupySearchQuery().apply {
dateRange = EntrupySearchQuery.DateRange.Last(7)
filters = listOf(
EntrupySearchFilter.Status(listOf(EntrupySearchFilter.AuthenticationStatus.Authentic))
)
resultMode = EntrupySearchResultMode.CountOnly
}

onSearchCompleted then receives totalCount, and items is empty.

Callback Behavior​

  • Exactly one of the two methods is called, on the main thread. The one exception is SDK_NOT_INITIALIZED, which is reported right away on the calling thread.
  • If you call EntrupyApp.cleanup() while a search is running, the search is dropped and neither method is called.

Error Codes​

errorCode is one of the EntrupyErrorCode constants (com.entrupy.sdk.listeners.EntrupyErrorCode):

CodeWhen
SDK_NOT_INITIALIZEDEntrupyApp.init was not called yet
UNAUTHORIZED_ACCESSThe user is not logged in, or the backend answered 401
FORBIDDENThe session ended during the search, or the backend answered 403
BAD_REQUESTThe query has a limit of 0 or less, or Last with negative days. No request is sent. Also when the backend answered 400
NOT_FOUND, TOO_MANY_REQUESTSThe backend answered 404 or 429
SERVICE_UNAVAILABLEThe backend answered 503
INTERNAL_SERVER_ERRORThe backend answered any other 5xx
UNKNOWN_ERRORAny other status, such as 409 or 422, or no HTTP status at all, for example when the device is offline

description is the backend's own message when it sent one, and a short English message otherwise.

Response Structure​

onSearchCompleted receives an EntrupySearchItemsResult (com.entrupy.sdk.model). Only the SDK creates it.

PropertyDescription
metadataHow the backend answered: metadata.resultMode is an EntrupySearchResultMode, so you can compare it with the query. null when the backend sent no metadata
totalCountHow many items match the query, across all pages
itemCountHow many items this page has, as the backend counted them
itemsThe items of this page, as EntrupyCaptureResult. Empty in count only mode
nextCursorThe cursor of the next page. null on the last page

The items are the same EntrupyCaptureResult that fetchSessionDetails returns, described in Authentication Data Model, without their timeline. Call fetchSessionDetails for an item's full timeline.

Next Steps​