Search credentials

1. Introduction
   • Example Request
2. Filtering
   • Logical Operators
     • AND
     • OR
     • NOT
   • Field Types & Comparison Operators
     • String Fields
     • UUID Fields
     • Enum Fields
     • Date Fields (YYYY-MM-DD)
     • DateTime Fields (ISO 8601)
     • Handling Null Values
     • In Operator Limitation for Null Values
3. Credentials Searchable Fields
   • Core Fields
   • Recipient Fields
   • Temporal Fields
4. Sorting
   • Credentials Sortable Properties
5. Pagination
6. Complete Example
7. Tips and Advanced Use
   • Implicit AND
     • Top-Level Logical Operators
     • Filter Condition Objects
     • Comparison Operator Expressions

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:

• filter – to define search conditions using AND, OR, and NOT logical operators.
• sort – containing property and order, allowing control over result ordering.
• Standard pagination using cursor and limit.

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

UUID Fields

UUID fields (such as publicId) only support exact matching. Each value must be a valid UUID — malformed values are rejected.

{
  "publicId": {
    "equals": "124a8110-1af5-4747-9308-e9d06bd1852a"
  }
}

• equals: Exact match (must be a valid UUID)
• in: Matches any value in an array (each must be a valid UUID)

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"
          ]
        }
      }
    ]
  }
}

{
  "filter": {},
  "sort": {
    "property": "createdAt",
    "order": "desc"
  },
  "limit": 25
}

{
  "data": [
    {
      "id": "01hz2f0c9ryvzajg20jqh9taab",
      "publicId": "124a8110-1af5-4747-9308-e9d06bd1852a",
      "groupId": "01g90279gp5sbmfek7wymcsvec",
      "status": "draft",
      "recipient": {
        "id": "01jmerb62apgachxwx6db76c7s",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "issueDate": "2022-01-01",
      "expiryDate": "2023-01-01",
      "attributes": {
        "recipient.name": "John Doe"
      },
      "customAttributes": {
        "custom.mentor": "Jane Doe"
      },
      "createdAt": "2022-01-01T00:00:00.000Z",
      "updatedAt": "2022-01-01T00:00:00.000Z"
    }
  ]
}