The Career Assignment object

Quick Summary: An assignment links a person to a career at a level. Assigning grants that level’s learnings and attaches the career’s skills; unassigning records career history first, so a person’s past careers remain readable.

The assigned person

Returned by GET /api/v1/careers/{id}/people.

Field	Type	Description
`id`	string	Opaque person id
`externalId`	string \| null	Your own identifier for this person — the Person resource’s `externalId`
`firstName` / `lastName`	string \| null	Name
`email`	string \| null	Email
`level`	object \| null	`{ id, name }` — the level this person holds within the career
`assignedAt`	string (ISO 8601 UTC) \| null	Server-stamped when the assignment was created. Read-only
`initiationDate`	string (ISO 8601 UTC) \| null	Caller-supplied date the person actually begins in the career

{
  "id": "4821",
  "externalId": "E-10422",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "ada@example.com",
  "level": { "id": "12", "name": "Level 2" },
  "assignedAt": "2026-03-11T08:22:10.000Z",
  "initiationDate": "2026-04-01T00:00:00.000Z"
}

The two dates have different owners. assignedAt is stamped by SkillsDB at the moment of the write and cannot be supplied; initiationDate is yours, and records when the person actually begins in the career.

The person’s career

Returned by GET /api/v1/people/{personId}/careers — the {personId} slot takes the person’s email address (or the opaque id from any response). Previous (ended) assignments are included by default — pass ?includePrevious=false to exclude them.

Field	Type	Description
`id`	string	Opaque career id
`name`	string \| null	Career name
`careerType`	string \| null	The family the career belongs to
`isPrevious`	boolean	`true` for an ended assignment, `false` for a current one
`assignedAt`	string (ISO 8601 UTC) \| null	When the assignment was created
`initiationDate`	string (ISO 8601 UTC) \| null	When the person began in the career
`skillsCount`	number \| null	Skills on the career

{
  "id": "318",
  "name": "Welder",
  "careerType": "Trades",
  "isPrevious": false,
  "assignedAt": "2026-03-11T08:22:10.000Z",
  "initiationDate": "2026-04-01T00:00:00.000Z",
  "skillsCount": 24
}

The distribution

Returned by GET /api/v1/careers/{id}/distribution. Counted server-side — do not page through the assigned-people list to derive these numbers.

Field	Type	Description
`levels`	array	Headcount per career level, in level order
`flags`	array	Headcount per people-flag

Each bucket is { id, label, count }, where id is null for the catch-all bucket (for example No Flag).

{
  "levels": [{ "id": "12", "label": "Level 2", "count": 17 }],
  "flags": [{ "id": null, "label": "No Flag", "count": 17 }]
}

A credential bound to a manager sees only their span of control, so these counts reflect what the acting person is permitted to see — not necessarily the whole company.

Two rules that surprise integrations

GET /api/v1/careers/{id}/people lists the career’s holders only — every row carries a level and an assignedAt; an empty career is an empty list. GET /careers/{id}/distribution aggregates the same population server-side. Assigning is never an update. POST /api/v1/careers/{id}/people takes a list of people — identified by email address — each at their own level:

{ "people": [{ "email": "ada@example.com", "levelId": "12" }] }

Anyone already holding the career is skipped silently — no error, and no level change. If you need to move someone, use PATCH /api/v1/careers/{id}/people/{personId} with { "levelId": "13" } — the {personId} slot takes the person’s email (or the opaque id from any response); an integration that re-assigns expecting a correction will do nothing at all. Assigning fans out. Beyond the assignment row, it grants every learning attached to the target level and attaches the career’s skills to the person. One call against a hundred people is a large write, not a small one — budget it against your rate limit. Unassigning mirrors the shape by email: DELETE /api/v1/careers/{id}/people with { "emails": ["ada@example.com", "grace@example.com"] }. Both assign and unassign accept at most 500 people per call — a larger array is rejected with a 400 validation-error before anything is written, so split bigger batches into chunks.

Using the API

System Objects

Team Data

Errors

The Career Assignment object

The assigned person

The person’s career

The distribution

Two rules that surprise integrations

​The assigned person

​The person’s career

​The distribution

​Two rules that surprise integrations

The assigned person

The person’s career

The distribution

Two rules that surprise integrations