Quick Summary: People are the anchor of the whole API — every record in Team Data names a person. This group covers the person record itself, the company-defined attributes a person references (job titles, people types, access levels, countries), and the eleven org dimensions plus the manager hierarchy.
The resources
Addressing a person
Every person-shaped path slot on this API takes the person’s email address — the primary, documented form — or the opaqueid from any response. Request fields that reference a person are email fields (managerEmail, delegatedApproverEmail, { "email": ... }). Email is unique across all of SkillsDB, not just your company.
The field an integration should key on is externalId — your own identifier, carried on the person record for exactly this purpose.
Attributes are their own library
Job titles, people types, access levels and countries are company-configured lists, not free text on the person. A person references them; you manage the lists themselves through their own endpoints. Access levels are the one list you cannot extend — four are assignable (basic, manager, admin, fullaccess) and three are legacy and read-only.
Syncing a workforce
POST /api/v1/bulk/people takes a batch of people in one call — the shape an HRIS sync needs. For a single dimension, PUT /people/{id}/org-schema/{dimension} replaces that dimension with exactly the supplied list, which is what makes a repeatable sync idempotent.
SCIM and this API are alternatives, not layers. If your identity provider provisions people through SkillsDB’s SCIM integration, do not also sync people through this API against the same tenant.