# Certification Intelligence

Find stored certification types, records, subjects, dates, and evidence filenames.

Canonical HTML: https://developer.shelfcycle.com/guides/certifications

Find the certification information stored in ShelfCycle by type, business record, status, date, and recorded evidence filename.

Certification Intelligence supports four connected workflows:

- `GET /certification-types` lists the organization's certification vocabulary.
- `GET /certification-records` finds individual stored records.
- `GET /certification-records/{recordId}` returns one exact record.
- `GET /certification-subjects` finds customers, suppliers, products, and customer addresses with matching records.

## Access

The endpoints require `certifications:read` plus the acting user's current access to the related customer, supplier, product, or customer address. `GET /me` reports `effectiveCapabilities.certifications.view` and the available `viewableSubjectTypes`.

```bash
curl "$SHELFCYCLE_API_BASE_URL/certification-types?subjectType=supplier" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Supplier quality workspace"
```

## Learn the organization's vocabulary

Use `GET /certification-types` before a broad search when the workflow needs the exact type title or ID used by the organization.

```json
{
  "data": [
    {
      "id": "certification-type-id",
      "title": "Third Party Audit",
      "description": "Annual third-party quality audit",
      "enabled": true,
      "documentationRequired": true,
      "subjectType": "supplier",
      "type": "certification_type"
    }
  ],
  "meta": {
    "populationCount": 8,
    "returnedRecords": 1,
    "complete": true,
    "hasMore": false,
    "nextCursor": null,
    "evaluatedAt": "2026-08-24T16:30:00.000Z",
    "requestId": "request-id"
  }
}
```

Filter by `subjectType` using `supplier`, `customer`, `product`, or `customer_address`. Add `includeDisabled=true` only when the workflow needs historical type configuration.

## Find stored records

Use `GET /certification-records` to search individual certification rows. Common filters include:

| Filter | Use it for |
| --- | --- |
| `typeId` or `typeQuery` | One exact certification type or matching type title and description. |
| `subjectTypes` and `subjectId` | One or more business record classes, or one exact business record. |
| `recordedStatuses` | Recorded `PENDING`, `ACTIVE`, or `EXPIRED` values. |
| `effectiveStates` | Current interpretation at the response's exact evaluation time: `pending`, `current`, `expired`, or `incomplete`. |
| `expiresAtOrAfter` and `expiresAtOrBefore` | Exact date-time boundaries for expiration review. |
| `evidenceRecordedState` | `recorded`, `not_recorded`, or `invalid_metadata`. |
| `evidenceFileNameQuery` | An explicit filename search when the source wording points to a recorded filename. |

```bash
curl "$SHELFCYCLE_API_BASE_URL/certification-records?subjectTypes=supplier&subjectId=supplier-id&effectiveStates=current&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

```json
{
  "data": [
    {
      "recordId": "certification-record-id",
      "resourceKind": "stored_certification_record",
      "type": {
        "id": "certification-type-id",
        "title": "Third Party Audit",
        "description": "Annual third-party quality audit",
        "enabled": true,
        "documentationRequired": true,
        "subjectType": "supplier"
      },
      "subject": {
        "subjectType": "supplier",
        "id": "supplier-id",
        "displayName": "Northstar Chemical",
        "externalId": "SUP-1042",
        "archived": false,
        "customerId": null,
        "locationId": null,
        "addressId": null
      },
      "recordedStatus": "ACTIVE",
      "effectiveState": "current",
      "validFrom": "2026-01-01T00:00:00.000Z",
      "validTo": "2026-12-31T23:59:59.000Z",
      "recordCompleteness": "populated",
      "evidence": {
        "recordedState": "recorded",
        "fileName": "northstar-third-party-audit-2026.pdf"
      },
      "matchBasis": ["unfiltered"],
      "searchedFields": [],
      "createdAt": "2026-01-02T14:00:00.000Z",
      "updatedAt": "2026-01-02T14:00:00.000Z"
    }
  ],
  "meta": {
    "populationCount": 1,
    "returnedRecords": 1,
    "complete": true,
    "hasMore": false,
    "nextCursor": null,
    "evaluatedAt": "2026-08-24T16:30:00.000Z",
    "currentState": true,
    "snapshotIsolatedAcrossRequests": false,
    "requestId": "request-id"
  }
}
```

`recordedStatus` preserves the status stored on the record. `effectiveState` interprets the record at the exact `meta.evaluatedAt` time, including its expiration boundary. `validFrom` remains informational record context.

The `evidence` object reports whether a filename was recorded and returns that filename when available. Use it as stored record context. The certification endpoints do not return file links or file contents.

> **Record meaning**: Certification results describe records stored in ShelfCycle. Present them as the organization's recorded certification information, with the returned status, dates, and evidence filename.

## Find subjects with matching records

Use `GET /certification-subjects` when the workflow needs a customer, supplier, product, or customer-address view rather than one row per certification record. It accepts the same record filters and returns each authorized subject once.

```bash
curl "$SHELFCYCLE_API_BASE_URL/certification-subjects?typeQuery=Third%20Party%20Audit&effectiveStates=current&subjectTypes=supplier" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Each row includes `matchingRecordCount`, `currentMatchingRecordCount`, and `latestCurrentValidTo`. Use those returned counts directly when building summaries.

For an exact subject question, first request that subject without a type or text filter to understand the complete visible record set. Then apply the requested type or date filters. This keeps a filtered zero result clearly tied to the selected subject and filter.

## Inspect one exact record

After selecting a `recordId`, use `GET /certification-records/{recordId}` for the exact stored row:

```bash
curl "$SHELFCYCLE_API_BASE_URL/certification-records/certification-record-id" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

The detail response uses the same type, subject, status, date, completeness, and evidence fields as the list row.

## Continue and refresh

When `meta.hasMore` is true, call the same collection endpoint again with `meta.nextCursor` by itself. Do not combine a cursor with the original filters.

Certification responses include `meta.evaluatedAt`, `currentState: true`, and `snapshotIsolatedAcrossRequests: false`. A continued traversal keeps its evaluation time for consistent effective-state interpretation. Restart from the original filters for a new current view.