API Reference

Search credentials

post https://api.certifier.io/v1/credentials/search

Use this endpoint to list credentials.

Table of Contents

  1. Introduction
  2. Filtering
  3. Credentials Searchable Fields
  4. Sorting
  5. Pagination
  6. Complete Example
  7. Tips and Advanced Use

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

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"
        }
      }
    ]
  }
}
Language
Credentials
OAuth2
Click Try It! to start a request and see the response here!