CertifierCertifier
Credentials

Search credentials

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

  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"
          ]
        }
      }
    ]
  }
}
POST
/v1/credentials/search

Authorization

BearerAuth
AuthorizationBearer <token>

Provide your access token in the Authorization header with Bearer auth-scheme. You can view and manage your access tokens in the Certifier Dashboard.

In: header

Header Parameters

Certifier-Version*string

API version header. Required for all requests.

Request Body

application/json

filter?

Filter object with AND, OR, NOT operators and field conditions. Supports filtering by id, publicId, groupId, status, recipientId, recipient.name, recipient.email, issueDate, expiryDate, createdAt, updatedAt

sort?

Sorting options

cursor?string

Cursor for pagination

limit?integer

Number of items to return (default: 20)

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.certifier.io/v1/credentials/search" \  -H "Certifier-Version: 2022-10-26" \  -H "Content-Type: application/json" \  -d '{}'
{
  "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"
    }
  ],
  "pagination": {
    "prev": null,
    "next": null
  }
}

{
  "error": {
    "code": "missing_version",
    "message": "The request is missing the required Certifier-Version header"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "A valid authentication token was not provided with the request"
  }
}
{
  "error": {
    "code": "rate_limited",
    "message": "You have exceeded the rate limit"
  }
}
{
  "error": {
    "code": "internal_server_error",
    "message": "There was a problem on Certifier's end"
  }
}

Issue a credential POST

Use this endpoint to issue a draft credential and change the status from `draft` to `issued`. You can only issue credentials with `status = "draft"`.

Send a credential POST

Use this endpoint to send a published credential to a recipient. You can only send credentials with `status = "issued"`.

On this page

Introduction
Example Request
Filtering
Logical Operators
AND
OR
NOT
Field Types & Comparison Operators
String Fields
Enum Fields
Date Fields (YYYY-MM-DD)
DateTime Fields (ISO 8601)
Handling Null Values
in Operator Limitation for Null Values