Skip to content

API reference — overview

What it is

The HTTP API surface of ManpowerIQ, organised by capability. These pages are generated from the live OpenAPI spec (/swagger/v1/swagger.json — 157 paths, 215 operations across 53 controller groups) and annotated with the things the spec can't carry: role-gating (from the RBAC matrix), the why, gotchas, and the F-findings. They do not reproduce the full request/response schema per endpoint — the live Swagger UI at /swagger is the source of record for that; each page links out.

Conventions across every endpoint

Auth. Every endpoint requires a Bearer JWT (global security: [{ Bearer: [] }]) except a small set of [AllowAnonymous] ones: the login endpoints and the dev-only diagnostics. The token is an 8-hour access token (no refresh) — see Authentication & RBAC. Per-endpoint authorization is a permission policy (e.g. [Authorize("employee.view")]); the required code is listed on each group page and resolves through the RBAC matrix.

Errors — RFC 7807 ProblemDetails. Failures return a ProblemDetails body:

Status Meaning
400 Validation failure (FluentValidation → ToValidationProblem)
401 No/expired token
403 Authenticated but missing the required permission
404 Not found (or a dev-only endpoint reached outside Development)
409 Domain conflict — carries a structured extensions.code, e.g. GRADE_PROTECTED / GRADE_REFERENCED (see Exceptions convention)

Locale. Pass Accept-Language: en or ar (or the locale query param where present) to localise messages; bilingual data carries Name_1_English / Name_2_Arabic — see Internationalisation.

Pagination is per-endpoint, not global. Some list endpoints accept Page/PageSize (or take); many return the full result set. There is no global pagination envelope — consult Swagger per endpoint.

Naming. Routes are kebab/lowercase; admin-CRUD surfaces live under /api/admin/* (the coexistence pattern).

The groups

System — cross-cutting auth, identity, platform, and the dev-only diagnostics:

Admin — reference-data and configuration CRUD:

Operational — the daily workflow:

Honest status (carried into the reference)

  • The 6 *Diagnostics groups are dev-only ([AllowAnonymous], gated to IsDevelopment()); three even carry a "remove or restrict before production" TODO. Not integrations.
  • Employees and skills are import-only — no create/edit endpoints (Employees is GET-only); people enter via Excel import.
  • LookupsController is read-only (all GET).
  • DemandPlanStatus.Locked is a defined-but-unreachable enum value (F1); the published-roster Approved waypoint is dead (publish goes straight to Published).