Quick Summary: Create an API key in Settings → API Credentials, send it as a Bearer token, call
/api/v1/ping to prove the connection, then make your first real call.1. Create an API key
A company administrator creates keys under Settings → API Credentials: give it a name, pick its scopes (for examplecareers:read), and choose the acting person — the API can never do more than that person could do in the app.
2. Prove the connection
/ping requires a valid key but no scope — it is the scope-free connectivity check.
3. Make your first real call
The conventions, in one paragraph
Every response is JSON with camelCase fields. Collections are{ data: [...], meta: { total, limit, offset } }; single resources are { data: {...} }. Ids are opaque strings. Timestamps are ISO 8601 UTC with a Z. Nullable fields are always present with an explicit null. Errors are RFC 9457 problem+json — see the error catalogue. The machine-readable contract is at /api/v1/openapi.json (no authentication needed).
How people are identified
The person identifier is the email address. Request bodies and query filters take emails only (email, emails, managerEmail, delegatedApproverEmail, ?email=), and path slots like /people/{id} take the email as the primary form — the opaque person id from any response also works there, and the two forms never collide (ids are all digits, an email always contains @). Responses keep opaque ids. Resolution is bounded by your company: an email held by another company answers exactly like one that does not exist — a 404 in a path slot, a 400 with code unknown_person in a body or query field. One edge — if your data holds case- or whitespace-variant duplicates of the same address, the API refuses with a 409 rather than pick a record; resolve the duplicates or use the opaque id.
Writes can notify people
Some write operations notify affected people by email as a side effect — assigning learning emails the assignee, launching a survey notifies its participants, submitting a training for approval notifies approvers. The API follows the company’s notification configuration exactly as the app does: whatever your administrators have enabled in SkillsDB applies to API-originated changes too, and there is no per-request switch to force or suppress an email in v1. If a bulk sync should run silently, adjust the company’s notification settings for that window rather than expecting a request flag.Explore with Postman
A ready-made Postman collection is generated from the same contract. Import it, open the collection’s Variables tab, paste your key intoapiKey and point baseUrl at your environment — every request inherits the collection-level authentication and common headers, so nothing needs configuring per request. Write requests carry an optional, one-click Idempotency-Key header prefilled with a GUID, and request bodies come prefilled with working examples.
Where next
- Authentication — key lifecycle, rotation, revocation
- Pagination, Filtering, Sorting
- Idempotency — safe retries for writes
- Rate limits
- The endpoint reference in this section’s sidebar — one section per resource, one page per operation