Table of Contents

Introduction
- Example Request
Filtering
- Logical Operators
  - AND
  - OR
  - NOT
- Field Types & Comparison Operators
Credentials Searchable Fields
Sorting
- Credentials Sortable Properties
Pagination
Complete Example
Tips and Advanced Use
- Implicit AND

Introduction

The Credentials Search API allows you to find and filter credentials using structured queries with logical operators, sorting, and pagination.

A search request payload consists of:

Example Request

POST /v1/credentials/search
Content-Type: application/json

{
  "filter": {
    "AND": [
      {
        "status": {
          "equals": "issued"
        }
      },
      {
        "recipient": {
          "name": {
            "contains": "John"
          }
        }
      }
    ]
  },
  "sort": {
    "property": "createdAt",
    "order": "desc"
  },
  "cursor": "some_cursor_value",
  "limit": 25
}

Filtering

Filter allows complex queries by combining multiple conditions using logical operators.

Logical Operators

Logical operators define how multiple conditions are combined.

`AND`

All conditions must be met.

{
  "filter": {
    "AND": [
      {
        "status": {
          "equals": "issued"
        }
      },
      {
        "recipient": {
          "email": {
            "endsWith": "@company.com"
          }
        }
      }
    ]
  }
}

`OR`

At least one condition must be met.

{
  "filter": {
    "OR": [
      {
        "status": {
          "equals": "draft"
        }
      },
      {
        "status": {
          "equals": "expired"
        }
      }
    ]
  }
}

`NOT`

Excludes records that match the condition.

{
  "filter": {
    "NOT": [
      {
        "status": {
          "equals": "expired"
        }
      }
    ]
  }
}

Operators can be combined:

{
  "filter": {
    "AND": [
      {
        "NOT": [
          {
            "recipient": {
              "email": {
                "endsWith": "@company.com"
              }
            }
          }
        ]
      },
      {
        "recipient": {
          "name": {
            "startsWith": "John"
          }
        }
      }
    ]
  }
}

Field Types & Comparison Operators

Comparison operators define how field values are filtered.

String Fields

{
  "recipient": {
    "name": {
      "contains": "John"
    }
  }
}

equals: Exact match
contains: Partial match
startsWith: Prefix match
endsWith: Suffix match
in: Matches any value in an array

Enum Fields

{
  "status": {
    "in": [
      "draft",
      "expired"
    ]
  }
}

equals: Exact match
in: Matches any value in an array

Date Fields (`YYYY-MM-DD`)

{
  "issueDate": {
    "gte": "2024-01-01"
  }
}

equals: Exact match
lt: Less than
lte: Less than or equal
gt: Greater than
gte: Greater than or equal

DateTime Fields (ISO 8601)

{
  "createdAt": {
    "gte": "2025-02-21T14:18:33Z"
  }
}

equals: Exact match
lt: Less than
lte: Less than or equal
gt: Greater than
gte: Greater than or equal

Handling Null Values

{
  "expiryDate": {
    "equals": null
  }
}

{ "expiryDate": { "equals": null } }: Matches records where the field is null.
{ NOT: [{ "expiryDate": { "equals": null } }] }: Excludes records where the field is null.

`in` Operator Limitation for Null Values

The in operator does not support null values. If you need to match null alongside other values, use an OR logical statement instead:

{
  "filter": {
    "OR": [
      {
        "recipientId": {
          "equals": null
        }
      },
      {
        "recipientId": {
          "in": [
            "01jmerb62apgachxwx6db76c7s",
            "01jmerbnaa9r183ry7a4mpe4v8"
          ]
        }
      }
    ]
  }
}

Credentials Searchable Fields

Core Fields

id (string): Internal identifier
publicId (string): Public-facing identifier
groupId (string): Group identifier
status (enum): Credential status
- Available values: "draft", "scheduled", "issued", "expired"

Recipient Fields

recipientId (string, nullable): Recipient identifier

Nested under recipient key:

name (string): Recipient's full name
email (string): Recipient's email address

⚠ Dot notation is not supported. Use object notation instead:

{
  "filter": {
    "AND": [
      {
        "recipient": {
          "email": {
            "endsWith": "@company.com"
          }
        }
      }
    ]
  }
}

Temporal Fields

issueDate (date): When the credential was issued
expiryDate (date, nullable): When the credential expires
createdAt (datetime): When the record was created
updatedAt (datetime): When the record was last updated

Sorting

Specify sorting rules using property and order.

{
  "sort": {
    "property": "createdAt",
    "order": "asc"
  }
}

Credentials Sortable Properties

id (default)
createdAt
updatedAt
issueDate
expiryDate

Sort direction:

asc: Ascending order
desc: Descending order (default)

Pagination

Use cursor and limit to navigate through results (see pagination docs).

{
  "cursor": "some_cursor_value",
  "limit": 25
}

Complete Example

{
  "filter": {
    "AND": [
      {
        "status": {
          "equals": "issued"
        }
      },
      {
        "recipient": {
          "email": {
            "endsWith": "@company.com"
          }
        }
      },
      {
        "OR": [
          {
            "issueDate": {
              "gte": "2024-01-01"
            }
          },
          {
            "expiryDate": {
              "lte": "2024-12-31"
            }
          }
        ]
      }
    ]
  },
  "sort": {
    "property": "createdAt",
    "order": "desc"
  },
  "cursor": "some_cursor_value",
  "limit": 25
}

Tips and Advanced Use

Implicit `AND`

Top-Level Logical Operators

At the top level, AND, OR, and NOT operators can be combined, and they are implicitly joined by AND. The following query:

{
  "filter": {
    "AND": [
      {
        "status": {
          "equals": "issued"
        }
      },
      {
        "recipient": {
          "name": {
            "contains": "John"
          }
        }
      }
    ],
    "OR": [
      {
        "issueDate": {
          "gte": "2024-01-01"
        }
      },
      {
        "expiryDate": {
          "lte": "2024-12-31"
        }
      }
    ]
  }
}

is functionally equivalent to:

{
  "filter": {
    "AND": [
      {
        "status": {
          "equals": "issued"
        }
      },
      {
        "recipient": {
          "name": {
            "contains": "John"
          }
        }
      },
      {
        "OR": [
          {
            "issueDate": {
              "gte": "2024-01-01"
            }
          },
          {
            "expiryDate": {
              "lte": "2024-12-31"
            }
          }
        ]
      }
    ]
  }
}

This means you can freely use multiple top-level logical operators without explicitly nesting them under a single AND.

Filter Condition Objects

Implicit AND can also be used putting multiple properties inside of a single comparison operator group.

The following query:

{
  "filter": {
    "AND": [
      {
        "status": {
          "equals": "issued"
        },
        "issueDate": {
          "gte": "2024-01-01"
        }
      }
    ]
  }
}

is functionally equivalent to:

{
  "filter": {
    "AND": [
      { 
        "status": {
          "equals": "issued"
        }
      },
      { 
        "issueDate": {
          "gte": "2024-01-01"
        }
      }
    ]
  }
}

Comparison Operator Expressions

Finally, multiple comparison operators inside the same field object are implicitly treated as a single AND.

The following query:

{
  "filter": {
    "AND": [
      {
        "issueDate": {
          "gte": "2024-01-01",
          "lte": "2025-01-01"
        }
      }
    ]
  }
}

is functionally equivalent to:

{
  "filter": {
    "AND": [
      {
        "issueDate": {
          "gte": "2024-01-01"
        }
      },
      {
        "issueDate": {
          "lte": "2025-01-01"
        }
      }
    ]
  }
}