Skip to main content

Filtering

Filtering is handled consistently across different resources. Pass query parameters to filter lists and find specific items efficiently.

The following resources support filterable lists:

  • Keys
  • Identifers
  • Credential schemas
  • Proof schemas
  • Credentials
  • Proof requests
  • Trust anchors
  • Trust entities

Below are the most important filtering capabilities available across these resources. Note that not every filtering method is available for all resource types; each endpoint supports a subset of these options based on the nature of the data being filtered.

By text​

Name​

The name parameter filters items whose names start with the provided string. The search is case-insensitive, so "digi" will match items starting with "Digital", "DIGITAL", or "digital".

Credentials and proof requests do not have names; for these resources this parameter filters by the schema used. For example, "U.S." will match credentials whose schema starts with "U.S. Passport" or "U.S. Driver License".

Exact matching​

The exact[] parameter modifies how text filters behave, changing them from "starts with" matching to exact string matching, still case-insensitive. The parameter accepts multiple values using either array notation (exact[]=name&exact[]=schemaId) or repeated parameters (exact=name&exact=schemaId).

For example, without exact[], searching for "Digital" would match both "Digital" and "Digital Passport Schema". With exact[]=name, only items named exactly "Digital" would be returned.

The /credential and /history resources support advanced search capabilities using the searchText parameter combined with searchType[] to specify where to search.

The searchText parameter accepts a search string, while searchType[] determines which fields to search within. Unlike the name parameter which only matches items that start with the provided string, searchText searches for the string anywhere within the specified fields.

This advanced search is particularly useful for finding credentials based on their content rather than just metadata. For example, using "John" as the searchText with CLAIM_VALUE as the searchType[] will return any credentials that contain "John" anywhere within their claim values. If no searchType is specified, all fields in the enum are searched.

By date range​

Creation and modification dates​

All list endpoints support filtering by when items were created or last modified using date range parameters. These filters accept timestamps in RFC3339 format (e.g., "2023-06-09T14:19:57.000Z").

Use createdDateAfter and createdDateBefore to filter by creation time, or lastModifiedAfter and lastModifiedBefore to filter by modification time. You can use these parameters individually or combine them to create specific date ranges.

For example, to find all credential schemas created in the last 30 days, use createdDateAfter with a timestamp from 30 days ago. To find items modified within a specific week, combine lastModifiedAfter and lastModifiedBefore with the appropriate start and end timestamps.

Entity-specific dates​

Some resources offer additional date filters specific to their lifecycle events. These use the same RFC3339 timestamp format as creation and modification dates.

Credentials support issuanceDateAfter and issuanceDateBefore to filter by when credentials were actually issued to holders, as well as revocationDateAfter and revocationDateBefore for finding revoked credentials within specific timeframes.

Proof requests provide requestedDateAfter and requestedDateBefore to filter by when the proof request was sent to the holder, and completedDateAfter and completedDateBefore to find proofs that were successfully submitted within a given period.

By entity states​

Status/state filtering​

Many resources allow filtering by their current state or status within the system. The available states vary by resource type, reflecting each entity's specific lifecycle.

Credentials can be filtered using status[] with values like CREATED, OFFERED, ACCEPTED, SUSPENDED, REVOKED, or ERROR to find credentials at specific stages of their lifecycle.

Proof requests support proofStates[] filtering with states such as CREATED, PENDING, REQUESTED, ACCEPTED, REJECTED, or RETRACTED to track the progress of verification interactions.

Role-based filtering​

Several resources support filtering by the role an entity plays within the system.

Credentials can be filtered using the role parameter with values like HOLDER, ISSUER, or VERIFIER to find credentials based on your system's relationship to them - whether you issued them, hold them, or verified them.

Trust entities support role filtering to distinguish between entities trusted to issue credentials (ISSUER), verify credentials (VERIFIER), or perform both functions (BOTH).

Proof requests also use proofRoles[] to filter by whether your system is acting as the HOLDER (responding to requests) or VERIFIER (making requests) in the verification process.

Active vs. deactivated entities​

Some resources allow filtering by whether entities are currently active or have been deactivated.

Identifiers support filtering by operational status using the state parameter with values ACTIVE or DEACTIVATED to find only functional identifiers or those that have been taken out of service.

By UUID​

Most list endpoints support filtering by specific entity identifiers when you need to retrieve particular items. This is useful for targeted queries or when working with known sets of entities.

Use the ids[] parameter to filter by specific UUIDs. This accepts an array of identifiers, allowing you to retrieve multiple specific items in a single request rather than making individual calls for each entity.

By technical specifications​

Formats and types​

Many resources support filtering by their technical format or type, allowing you to work with specific implementations or standards.

Credential schemas can be filtered using formats[] to find schemas that use particular credential formats like SD_JWT_VC or MDOC. Note that you should enter a string matching the desired format as it is named in your configuration.

Identifiers support filtering by types[] with values like DID, KEY, or CERTIFICATE to distinguish between different identifier mechanisms. You can also filter by didMethods[] to find identifiers using specific DID methods like WEB or KEY.

Trust entities and trust anchors provide type[] filtering to distinguish between different trust management approaches and entity types within your trust infrastructure.

Key algorithms and storage​

Resources that work with cryptographic keys support filtering by their technical specifications, helping you manage keys based on their security properties and storage requirements.

Use keyTypes[] on the keys endpoint to filter by cryptographic algorithms like EDDSA or ECDSA. For identifiers, use keyAlgorithms[] to find identifiers that either use a specific algorithm directly (for key-based identifiers) or are associated with keys using that algorithm (for DIDs and certificates).

The keyStorages[] parameter filters by where keys are stored, with options like INTERNAL, HARDWARE, or other storage types defined in your system configuration.

By relationships​

Remote vs. local entities​

Many resources distinguish between entities created locally within your system versus those encountered through interactions with external actors. This helps separate your own managed entities from those belonging to external parties.

Use the isRemote parameter with boolean values to filter identifiers and keys. Setting isRemote=false returns only entities you created and control, while isRemote=true returns entities from external wallets, issuers, or verifiers that your system has interacted with.

Schema associations​

Resources often support filtering by their associated schemas, helping you find entities related to specific credential or proof templates.

Proof requests support filtering by proofSchemaIds[] to find all verification interactions that used specific proof schemas.

Trust anchor relationships​

Trust-related resources support filtering by their relationships within trust management hierarchies, helping you organize and query trust infrastructure.

Trust entities can be filtered using trustAnchorId to find all entities associated with a specific trust anchor, making it easy to see which issuers or verifiers belong to a particular trust framework.

Trust anchors themselves support filtering by isPublisher with values true or false to distinguish between trust anchors you publish versus those you subscribe to from external sources.