Certification Intelligence

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.

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,
      "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:

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,
        "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.

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.

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:

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.