Certification Intelligence

Find stored certification information by type, business record, renewal state, 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, customer addresses, warehouses, and supplier-product combinations with matching records.

Access

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

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.

{
  "data": [
    {
      "id": "certification-type-id",
      "title": "Third Party Audit",
      "description": "Annual third-party quality audit",
      "enabled": true,
      "documentationRequired": true,
      "expiryNoticeDaysBefore": 30,
      "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, customer_address, warehouse, or supplier_combination. Add includeDisabled=true only when the workflow needs historical type configuration. expiryNoticeDaysBefore supplies the notice window used to determine when a record is expiring.

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`.
`renewalStates`	Renewal timing at the same evaluation time: `current`, `expiring`, `expired`, `renewed`, or `not_tracked`.
`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.

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

{
  "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,
        "expiryNoticeDaysBefore": 30,
        "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",
      "renewalState": "expiring",
      "daysLeft": 24,
      "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.

renewalState applies the certification type's expiryNoticeDaysBefore setting at the same evaluation time. daysLeft is the number of organization-calendar days until expiration. A past record reports renewed when a current certification of the same type exists for the same subject.

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, customer-address, warehouse, or supplier-product-combination view rather than one result per certification record. It accepts the same record filters and returns each available subject once.

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.

Warehouse subjects carry the warehouse identity. A supplier_combination subject carries a combination object with shipFromLocationId, shipFromLocationName, productId, and productDisplayName, so a workflow can keep the certification tied to the exact supplier origin and product.

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:

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 records are read one page at a time. meta.populationCount and coverage.totalRecords are available only when the first page contains the complete matching result. Use returnedRecords, hasMore, and nextCursor for continued traversal.

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.