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
| Property | Type | Default | Description |
|---|---|---|---|
dateRange | DateRange? | DateRange.Last(30) | When the items were created. null searches without a date range |
filters | List<EntrupySearchFilter> | empty | The filters to apply |
resultMode | EntrupySearchResultMode | Results | Full results, or only the counts |
limit | Int | 20 | The maximum number of items per page. Must be greater than 0 |
cursor | List<String>? | null | Where 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
| Value | Description |
|---|---|
EntrupySearchResultMode.Results | Returns the items of the page |
EntrupySearchResultMode.CountOnly | Returns 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:
| Value | Description |
|---|---|
Authentic | Item is authentic |
UnderReview | Entrupy is still reviewing the item |
Invalid | Invalid submission |
NotSupported | Item type not supported |
Unidentified | Authenticity 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).
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:
| Value | Description |
|---|---|
None | No flag applied |
Flagged | Currently flagged |
Resolved | The 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):
| Code | When |
|---|---|
SDK_NOT_INITIALIZED | EntrupyApp.init was not called yet |
UNAUTHORIZED_ACCESS | The user is not logged in, or the backend answered 401 |
FORBIDDEN | The session ended during the search, or the backend answered 403 |
BAD_REQUEST | The 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_REQUESTS | The backend answered 404 or 429 |
SERVICE_UNAVAILABLE | The backend answered 503 |
INTERNAL_SERVER_ERROR | The backend answered any other 5xx |
UNKNOWN_ERROR | Any 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.
| Property | Description |
|---|---|
metadata | How the backend answered: metadata.resultMode is an EntrupySearchResultMode, so you can compare it with the query. null when the backend sent no metadata |
totalCount | How many items match the query, across all pages |
itemCount | How many items this page has, as the backend counted them |
items | The items of this page, as EntrupyCaptureResult. Empty in count only mode |
nextCursor | The 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
- See Programmatic Access to Session Data to fetch one item by Entrupy ID.
- Review Customer Support Integration for flag and support features.