The Certification object

Quick Summary: A certification is a library entry: a name, a description, the type it is grouped under, and the authority that issues it. Full management over the API. What a person holds — their record, its approval workflow, evidence and expiry — is the separate Person Certification resource.

Attributes

Field	Type	Description
`id`	string	Opaque certification id
`name`	string	Name
`description`	string \| null	Description
`type`	object \| null	`{ id, name }` of the certification type it is grouped under; `null` when untyped
`issuingAuthorityName`	string \| null	The organisation or body that issues it
`issuingAuthorityUrl`	string \| null	The issuing authority’s website
`labels`	array	`{ id, name }` of every label attached, in label order. Labels are attached and detached through the label endpoints
`holderCount`	integer	People holding the certification — directly, or through a career that includes it
`holdersWithFileCount`	integer	Holders who have attached at least one file as evidence
`createdAt` / `updatedAt`	string (ISO 8601 UTC)	Timestamps; `updatedAt` may be `null`

{
  "id": "87",
  "name": "Forklift Operator Licence",
  "description": "Required for warehouse floor access.",
  "type": { "id": "4", "name": "Regulatory" },
  "issuingAuthorityName": "National Safety Council",
  "issuingAuthorityUrl": "https://www.nsc.org",
  "labels": [{ "id": "12", "name": "Safety" }],
  "holderCount": 14,
  "holdersWithFileCount": 9,
  "createdAt": "2026-01-12T08:30:00.000Z",
  "updatedAt": null
}

A certification has no expiry of its own. Expiry belongs to a person’s record of it — two people can hold the same certification with different expiry dates.

Operations

Operation	Method and path	Requires scope
List certifications	`GET /api/v1/certifications`	`certifications:read`
Get a certification	`GET /api/v1/certifications/{id}`	`certifications:read`
Create a certification	`POST /api/v1/certifications`	`certifications:write`
Update a certification	`PATCH /api/v1/certifications/{id}`	`certifications:write`
Delete a certification	`DELETE /api/v1/certifications/{id}`	`certifications:write`

Listing

Filterable by name, issuingAuthorityName and type (the type’s name); sortable by name and createdAt. See Filtering and Sorting.

GET /api/v1/certifications?filter[type][eq]=Regulatory&sort=name

Creating and updating

name is required on create; description, certificationTypeId, issuingAuthorityName and issuingAuthorityUrl are optional. A certificationTypeId must be one of the company’s types — an unknown id is a field-level validation-error, never a silent dangling reference. On PATCH, an omitted field is left untouched and an explicit null clears description, certificationTypeId, issuingAuthorityName or issuingAuthorityUrl. Labels are not part of this body: attach and detach them through the label endpoints.

Deleting

Deletion is guarded. If anyone holds the certification, or any career includes it, the call answers 409 conflict with the counts:

{
  "type": "https://help.skillsdb.com/api-docs/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "People hold this certification or careers include it. Retry with ?confirm=true to delete it anyway (holders keep their records as history; career links are removed).",
  "confirmRequired": true,
  "dependencies": { "people": 14, "careers": 2 }
}

Retry with ?confirm=true to proceed: the certification is soft-deleted and disappears from the library and from every career; holders’ records stay as history. An unheld, unlinked certification deletes immediately with 204.

Permissions

Every call is the intersection of the key’s scopes and what the acting person may do in the app. Reads, creates and updates are broadly permitted; delete is restricted to global administrators, and a key acting as a person who cannot delete receives insufficient-permissions. Two roles hold no certification permissions at all in the app today, so a key bound to a person in one of them is refused on every certification endpoint with the same problem type — bind the key to a person who can manage certifications.

not-found — the id does not exist in your company (another company’s certification answers the same 404)
validation-error — a missing name, an over-long field, or an unknown certificationTypeId
conflict — the guarded delete above
insufficient-scope / insufficient-permissions — see Permissions

Using the API

System Objects

Team Data

Errors

The Certification object

Attributes

Operations

Listing

Creating and updating

Deleting

Permissions

​Attributes

​Operations

​Listing

​Creating and updating

​Deleting

​Permissions

​Related errors

Attributes

Operations

Listing

Creating and updating

Deleting

Permissions

Related errors