Filter and query operators

Filter and paginate the passes list using field conditions, string and set operators, and offset-based pagination.

Filter and query operators

Several pass-related endpoints accept a filter array that narrows results by pass data field. Use filters together with pagination to retrieve exactly the set of passes you need.

Filtering is supported on these endpoints:

• GET /api/{tenantId}/passes — list passes
• POST /api/{tenantId}/passes/pushUpdate — trigger a push update on a filtered set
• POST /api/{tenantId}/passes/export/token — export a filtered set

Retrieve passes with optional filtering, sorting, and pagination.

get

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/api/{tenantId}/passes

Authorization: Requires Pass.Read scope.

Filtering: By identifiers (e.g., identifiers.email), metadata fields (e.g., metadata.loyaltyTier), pass type, or installation status (apple, google).

Sorting: By id, passType, creationDate, lastUpdateDate, apple, google, or any identifier/metadata field.

Pagination: Zero-based pageIndex and pageSize. Total count in x-pagination-total header.

Use Cases: Search passes by customer attributes; monitor installation status; filter by loyalty tier or campaign flag.

Example — list loyalty passes, page 0:

GET /api/{tenantId}/passes?pageIndex=0&pageSize=20
    &filter[0].field=passType&filter[0].operator=equals&filter[0].value=loyalty
    &sortBy[0].field=creationDate&sortBy[0].direction=DESC

Example — passes installed on Apple Wallet:

GET /api/{tenantId}/passes?filter[0].field=installationStatus&filter[0].operator=contains&filter[0].value=apple

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

pageIndexinteger · int32Optional

Zero-based page index.

Default: 0

pageSizeinteger · int32Optional

Number of passes per page.

Default: 20

Responses

200

Paged list of passes returned successfully.

text/plainapplication/jsontext/json

Represents a pass returned by the API.

idstringOptional

Platform-assigned unique pass identifier. This is a random alphanumeric string generated at creation time and cannot be set by callers (e.g., xK9mP2nQr7sT).

secretstringOptional

Platform-generated opaque token used internally to authenticate pass delivery. Read-only; treat as confidential.

creationDateone ofOptional

Timestamp when the pass was created by the platform. Read-only. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings.

string · date-timeOptional

or

integer · int64Optional

lastUpdateDateone ofOptional

Timestamp of the most recent update. Equals CreationDate when no update has occurred. Read-only. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings.

string · date-timeOptional

or

integer · int64Optional

passTypestringOptional

Type of pass, matching a file in the tenant server/passes/ configuration.

get/api/{tenantId}/passes

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Paged list of passes returned successfully.

[
  {
    "id": "text",
    "secret": "text",
    "creationDate": "2026-08-07T23:25:42.821Z",
    "lastUpdateDate": "2026-08-07T23:25:42.821Z",
    "passType": "text",
    "identifiers": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": null
    },
    "additionalData": {
      "ANY_ADDITIONAL_PROPERTY": null
    },
    "providers": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Push update for passes matching the filter.

post

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/api/{tenantId}/passes/pushUpdate

Authorization: Requires Pass.Write scope.

Filtering: Same as GetPasses�identifiers, metadata, pass type, installation status.

Async: Updates are queued. 200 response means scheduled, not complete. Monitor via statistics endpoint.

Data Merge: Merged into each matching pass. Set UpdateMetadata=true for recomputation (slower). Adjust Throughput for concurrency.

Bulk Operations: Ideal for campaigns, loyalty updates, seasonal offers. Use CorrelationId for tracking.

Use Cases: Campaign push; loyalty tier changes; offer refresh; bulk metadata updates.

Example — push a seasonal offer to all loyalty passes:

POST /api/{tenantId}/passes/pushUpdate
    ?filter[0].field=passType&filter[0].operator=equals&filter[0].value=loyalty
            
{
  "additionalData": { "offer": "summer2025", "discount": "20%" },
  "options": {
    "updateMetadata": true,
    "throughput": 12,
    "correlationId": "campaign-summer-2025"
  }
}

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

Body

application/jsontext/jsonapplication/*+json

additionalDataobject · nullableOptional

Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags).

passTypestring · nullableOptional

Optional pass type to convert the pass to.

updateMetadatabooleanOptionalDeprecated

Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update

Default: false

Responses

200

Passes scheduled for update; returns the count in the response body.

text/plainapplication/jsontext/json

Result returned after scheduling a bulk push update operation.

passCountinteger · int32Optional

Count of passes scheduled for update.

post/api/{tenantId}/passes/pushUpdate

HTTPcURLJavaScriptPython

POST /api/{tenantId}/passes/pushUpdate HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "identifiers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "additionalData": null,
  "passType": null,
  "options": {
    "throughput": 1,
    "updateMetadata": true,
    "correlationId": null
  }
}

application/jsontext/jsonapplication/*+json

200

Passes scheduled for update; returns the count in the response body.

{
  "passCount": 1
}

Create a time-limited download token for exporting passes as Excel.

post

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/api/{tenantId}/passes/export/token

Returns a short-lived signed URL (valid 5 minutes) that can be used to download the xlsx without an Authorization header. Filters are embedded in the token.

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Bodyobject · Neo.Web.Api.Controllers.FilterModel[]

application/jsontext/jsonapplication/*+json

Filter specification for pass queries.

fieldstringOptional

Field to filter by. Supported values: passType — pass type name (string).installationStatus — concatenation of installed wallet names (e.g. "apple", "google", "applegoogle"). Use contains to test for a single wallet.identifiers.{key} — an external identifier (string).metadata.{key} — a metadata field. The comparison type (string, number, boolean, datetime) is resolved automatically from the pass configuration.

operatorstring · enumOptional

Comparison operator to apply.

Possible values:

valuestring[] · nullableOptional

Filter value(s). Interpretation depends on Operator and the metadata field's configured type: String fields (identifiers.*, passType, installationStatus, or metadata.* configured as string) — plain string value for most operators; an array of strings for in / notIn.Numeric fields (metadata configured as number) — decimal number as a string, e.g. "42" or "3.14". Parsed using invariant culture (. as decimal separator).Boolean fields (metadata configured as boolean) — "true" or "false" (case-insensitive).Date fields (metadata configured as datetime) — ISO 8601 date-time string with timezone, e.g. "2024-06-01T00:00:00+00:00" or "2024-06-01T00:00:00Z". The value is converted to a unix timestamp (seconds) before comparison against the stored unix timestamp. The query parameter name is value (repeated for multiple values). Single value (equals, contains, startsWith, …):

GET /passes?filter[0].field=passType&filter[0].operator=equals&filter[0].value=boarding

Multiple values (in / notIn):

GET /passes?filter[0].field=passType&filter[0].operator=in&filter[0].value=boarding&filter[0].value=loyalty

Date comparison (metadata field configured as datetime):

GET /passes?filter[0].field=metadata.eventDate&filter[0].operator=greaterThan&filter[0].value=2024-01-01T00:00:00Z

Boolean comparison (metadata field configured as boolean):

GET /passes?filter[0].field=metadata.isVip&filter[0].operator=equals&filter[0].value=true
```</example>

Responses

200

Download token created successfully.

text/plainapplication/jsontext/json

downloadUrlstringOptional

post/api/{tenantId}/passes/export/token

HTTPcURLJavaScriptPython

POST /api/{tenantId}/passes/export/token HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 57

[
  {
    "field": "text",
    "operator": "Contains",
    "value": [
      "text"
    ]
  }
]

application/jsontext/jsonapplication/*+json

200

Download token created successfully.

{
  "downloadUrl": "text"
}

Filter request shape

Each filter condition is a FilterModel object with three fields:

Field	Type	Description
field	string	The pass data field to filter on (e.g. passType, loyaltyTier)
operator	string	The comparison operator (see below)
value	string[]	One or more values to compare against. Omit for isEmpty and isNotEmpty.

Filters are passed as indexed query parameters:

filter[0].field=passType&filter[0].operator=equals&filter[0].value=boarding

Multiple conditions are combined with logical AND:

filter[0].field=passType&filter[0].operator=equals&filter[0].value=boarding
&filter[1].field=loyaltyTier&filter[1].operator=isNotEmpty

Operators

String operators

These operators compare the field value against a single string.

Operator	Behaviour
equals	Exact match
notEquals	Does not match
contains	Field contains the value as a substring
startsWith	Field starts with the value
endsWith	Field ends with the value

Example — passes with a loyalty tier that contains "gold":

filter[0].field=loyaltyTier&filter[0].operator=contains&filter[0].value=gold

Presence operators

These operators check whether a field has a value. No value parameter is required.

Operator	Behaviour
isEmpty	Field is absent or null
isNotEmpty	Field has a non-null value

Example — passes where externalId is not set:

filter[0].field=externalId&filter[0].operator=isEmpty

Set operators

These operators match against a list of values. Repeat the value parameter to supply multiple entries.

Operator	Behaviour
in	Field matches any value in the list
notIn	Field matches none of the values in the list

Example — passes of type boarding or loyalty:

filter[0].field=passType&filter[0].operator=in&filter[0].value=boarding&filter[0].value=loyalty

in and notIn are available via the API only. The back-office passes table does not expose these operators in its filter controls.

Pagination

The passes list endpoint uses offset-based pagination.

Parameter	Type	Default	Description
pageIndex	integer	0	Zero-based page index
pageSize	integer	20	Number of results per page

The response includes an x-pagination-total header with the total number of matching passes across all pages.

To retrieve all passes in batches, increment pageIndex until the full count is consumed.

Combining filters and pagination

Filters and pagination parameters are independent query parameters and can be combined freely.