> ## Documentation Index
> Fetch the complete documentation index at: https://help.skillsdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Certification Type object

> The families certifications are grouped under, in display order

<Info>
  **Quick Summary:** Certification types organise the [certification library](/api-docs/resources/certification) into families (for example *Regulatory* and *Vendor*). Each type carries its display position and how many certifications use it. A type that is still in use cannot be deleted without confirming.
</Info>

## Attributes

| Field                     | Type                  | Description                                 |
| ------------------------- | --------------------- | ------------------------------------------- |
| `id`                      | string                | Opaque certification type id                |
| `name`                    | string                | Name                                        |
| `description`             | string \| null        | Description                                 |
| `position`                | integer               | 1-based display position within the company |
| `certificationCount`      | integer               | Live certifications grouped under this type |
| `createdAt` / `updatedAt` | string (ISO 8601 UTC) | Timestamps; `updatedAt` may be `null`       |

```json theme={null}
{
  "id": "4",
  "name": "Regulatory",
  "description": "Mandated by law or regulator.",
  "position": 1,
  "certificationCount": 6,
  "createdAt": "2026-01-12T08:30:00.000Z",
  "updatedAt": null
}
```

## Operations

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

The list is always in display order (`position` ascending) and takes no filters.

### Creating and updating

`name` is required on create (up to 100 characters); `description` is optional. A new type is placed at the **end** of the order. On `PATCH`, an omitted field is left untouched and an explicit `null` clears the description.

### Reordering

```http theme={null}
POST /api/v1/certification-types/reorder
{ "ids": ["4", "2", "7"] }
```

The body must list **every** certification type id of the company exactly once, in the desired order; the response is the full list in its new order. A partial list, a duplicate, or an id from another company is [422 unprocessable](/api-docs/errors/unprocessable).

### Deleting

Deletion is guarded. While certifications still use the type, the call answers [409 conflict](/api-docs/errors/conflict):

```json theme={null}
{
  "type": "https://help.skillsdb.com/api-docs/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Certifications still use this type. Retry with ?confirm=true to delete it anyway (those certifications are left without a type).",
  "confirmRequired": true,
  "dependencies": { "certifications": 6 }
}
```

Retry with `?confirm=true` to proceed: the type is soft-deleted and each certification that used it is left with `type: null`. An unused type deletes immediately with `204`.

## Permissions

Any person who can read certifications in the app can read types. **Creating, updating, reordering and deleting types is restricted to global administrators**; a key acting as anyone else receives [insufficient-permissions](/api-docs/errors/insufficient-permissions) on those operations even when it holds `certifications:write`.

## Related errors

* [not-found](/api-docs/errors/not-found) — the id does not exist in your company
* [validation-error](/api-docs/errors/validation-error) — a missing or over-long name
* [unprocessable](/api-docs/errors/unprocessable) — an incomplete or foreign reorder list
* [conflict](/api-docs/errors/conflict) — the guarded delete above