Skip to content

API reference / RivetIT

Integration

POST /oauth/token Public

OAuth2 client-credentials token for an integration client

Public (no Bearer). application/x-www-form-urlencoded with grant_type=client_credentials, client_id and client_secret (or HTTP Basic). Optional scope (space separated; must be a subset of the client's scopes, default all of them). Returns a signed access token valid for 10 minutes that is accepted ONLY on /lms/*, /employees/* and /departments/*. Every authentication failure is the same 401 invalid_client; repeated failures per IP and per client are throttled (429). Clients are managed in Administration > API Keys.

Request body (application/x-www-form-urlencoded, required)

FieldTypeDescription
grant_typerequired string (client_credentials)
client_idrequired string
client_secretrequired string (password)
scope string

Example request

curl -X POST "https://YOUR-HOST/api/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"ic_0123456789abcdef0123","client_secret":"string","scope":"lms:read lms:completions:read"}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/oauth/token",
    json={
        "grant_type": "client_credentials",
        "client_id": "ic_0123456789abcdef0123",
        "client_secret": "string",
        "scope": "lms:read lms:completions:read"
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      "grant_type": "client_credentials",
      "client_id": "ic_0123456789abcdef0123",
      "client_secret": "string",
      "scope": "lms:read lms:completions:read"
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/oauth/token");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"grant_type":"client_credentials","client_id":"ic_0123456789abcdef0123","client_secret":"string","scope":"lms:read lms:completions:read"}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Access token

FieldTypeDescription
access_token string
token_type string
expires_in integer
scope string
Example response
json
{
    "access_token": "string",
    "token_type": "Bearer",
    "expires_in": 600,
    "scope": "lms:read lms:assign"
}

400invalid_request, unsupported_grant_type or invalid_scope

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

401invalid_client

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

429rate_limited (Retry-After)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /lms/courses Bearer token or API key

Published course catalog

Scope lms:read. Published, non-archived courses only; each is its latest published revision. Limited to the client's department scope (all departments, or only courses linked to its departments by a live rule, a rule naming one of its people, or an assignment or completion of one of its people); departments and requirements list only what touches the allowed departments. Cursor paging, incremental sync with updated_since.

Parameters

NameInTypeDescription
limitqueryinteger
cursorquerystringOpaque `next_cursor` from the previous page
updated_sincequerystring (date-time)RFC 3339 timestamp; only records changed at or after it

Example request

curl "https://YOUR-HOST/api/v1/lms/courses" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/lms/courses",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/lms/courses", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/lms/courses");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Courses

FieldTypeDescription
data array of object
data[].id string Stable course id (12 characters)
data[].kind string (training | document)
data[].code string
data[].external_code string The code the QMS knows the course by
data[].title string
data[].description string
data[].status string (published)
data[].revision integer Published revision number
data[].revision_id integer
data[].departments array of string Departments targeted by the course's active requirement rules
data[].est_minutes integer
data[].validity_months integer
data[].category string
data[].requirements array of object
data[].requirements[].name string
data[].requirements[].required boolean
data[].requirements[].one_time boolean
data[].requirements[].all_people boolean
data[].updated_at string (date-time)
next_cursor string
Example response
json
{
    "data": [
        {
            "id": "string",
            "kind": "training",
            "code": "string",
            "external_code": "string",
            "title": "string",
            "description": "string",
            "status": "published",
            "revision": 1,
            "revision_id": 1,
            "departments": [
                null
            ],
            "est_minutes": 1,
            "validity_months": 1,
            "category": "string",
            "requirements": [
                null
            ],
            "updated_at": "2026-01-01T09:00:00Z"
        }
    ],
    "next_cursor": "string"
}

400invalid_limit, invalid_cursor, invalid_updated_since, invalid_department_id, invalid_odoo_employee_id, invalid_status, invalid_json, idempotency_key_required or idempotency_key_invalid

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /lms/courses/{id} Bearer token or API key

One published course

Scope lms:read. id is the course id from the list (12 characters). Unpublished, archived, unknown and out-of-department-scope ids are all the same 404.

Parameters

NameInTypeDescription
idrequiredpathstring

Example request

curl "https://YOUR-HOST/api/v1/lms/courses/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/lms/courses/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/lms/courses/1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/lms/courses/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Course

FieldTypeDescription
data object
data.id string Stable course id (12 characters)
data.kind string (training | document)
data.code string
data.external_code string The code the QMS knows the course by
data.title string
data.description string
data.status string (published)
data.revision integer Published revision number
data.revision_id integer
data.departments array of string Departments targeted by the course's active requirement rules
data.est_minutes integer
data.validity_months integer
data.category string
data.requirements array of object
data.requirements[].name string
data.requirements[].required boolean
data.requirements[].one_time boolean
data.requirements[].all_people boolean
data.updated_at string (date-time)
Example response
json
{
    "data": {
        "id": "string",
        "kind": "training",
        "code": "string",
        "external_code": "string",
        "title": "string",
        "description": "string",
        "status": "published",
        "revision": 1,
        "revision_id": 1,
        "departments": [
            "string"
        ],
        "est_minutes": 1,
        "validity_months": 1,
        "category": "string",
        "requirements": [
            {
                "name": null,
                "required": null,
                "one_time": null,
                "all_people": null
            }
        ],
        "updated_at": "2026-01-01T09:00:00Z"
    }
}

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

404not_found (unknown, unpublished or not servable; the two are not distinguished)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /lms/assignments Bearer token or API key

List assignments

Scope lms:read. Only assignments of people in the client's department scope. Filters employee (RivetIT id), odoo_employee_id, course, status (open, completed, waived, cancelled), external_system, external_ref, updated_since.

Parameters

NameInTypeDescription
limitqueryinteger
cursorquerystringOpaque `next_cursor` from the previous page
updated_sincequerystring (date-time)RFC 3339 timestamp; only records changed at or after it
employeequerystring
odoo_employee_idquerystring
coursequerystring
statusquerystring (open | completed | waived | cancelled)
external_systemquerystring
external_refquerystring

Example request

curl "https://YOUR-HOST/api/v1/lms/assignments" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/lms/assignments",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/lms/assignments", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/lms/assignments");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Assignments

FieldTypeDescription
data array of object
data[].id string
data[].employee object
data[].employee.rivetit_id string
data[].employee.odoo_employee_id string
data[].course_id string
data[].course_revision integer
data[].status string (open | completed | waived | cancelled)
data[].overdue boolean
data[].required boolean
data[].reason string
data[].due_on string (date)
data[].original_due_on string (date)
data[].external_system string
data[].external_ref string
data[].completion_id string
data[].created_at string (date-time)
data[].closed_at string (date-time)
data[].close_reason string
data[].updated_at string (date-time)
data[].revision integer
next_cursor string
Example response
json
{
    "data": [
        {
            "id": "asg_123",
            "employee": {
                "rivetit_id": null,
                "odoo_employee_id": null
            },
            "course_id": "string",
            "course_revision": 1,
            "status": "open",
            "overdue": true,
            "required": true,
            "reason": "string",
            "due_on": "string",
            "original_due_on": "string",
            "external_system": "string",
            "external_ref": "string",
            "completion_id": "string",
            "created_at": "2026-01-01T09:00:00Z",
            "closed_at": "2026-01-01T09:00:00Z",
            "close_reason": "string",
            "updated_at": "2026-01-01T09:00:00Z",
            "revision": 1
        }
    ],
    "next_cursor": "string"
}

400invalid_limit, invalid_cursor, invalid_updated_since, invalid_department_id, invalid_odoo_employee_id, invalid_status, invalid_json, idempotency_key_required or idempotency_key_invalid

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
POST /lms/assignments Bearer token or API key

Create (or reuse) an assignment

Scope lms:assign. Idempotency-Key is required: the same key with the same body replays the stored response (header Idempotent-Replay: true), the same key with a different body is 422 idempotency_key_reuse; keys are kept 24 hours and only successful results are stored. The employee is identified by odoo_employee_id or rivetit_id (never by name). The course must have a published revision. Created through the assignment engine, so the training ledger stays valid. 201 when a new assignment was created, 200 when an open assignment for the employee and course (or the same external reference) already existed. The employee and the course must be inside the client's department scope; outside it the answer is exactly the one for an unknown employee or course (422 employee_not_found / course_not_found), and an external_ref held outside the scope is the same 409 external_ref_conflict.

Parameters

NameInTypeDescription
Idempotency-Keyrequiredheaderstring

Request body (application/json, required)

FieldTypeDescription
employeerequired object Exactly the identifiers odoo_employee_id and/or rivetit_id (if both, they must be the same person)
employee.odoo_employee_id string
employee.rivetit_id string
course_idrequired string
due_onrequired string (date) Today or later
source string
external_system string
external_ref string Maps to exactly one assignment; send with external_system

Example request

curl -X POST "https://YOUR-HOST/api/v1/lms/assignments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"employee":{"odoo_employee_id":"string","rivetit_id":"string"},"course_id":"string","due_on":"string","source":"qms","external_system":"qms","external_ref":"NCR-0381"}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/lms/assignments",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "employee": {
            "odoo_employee_id": "string",
            "rivetit_id": "string"
        },
        "course_id": "string",
        "due_on": "string",
        "source": "qms",
        "external_system": "qms",
        "external_ref": "NCR-0381"
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/lms/assignments", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "employee": {
          "odoo_employee_id": "string",
          "rivetit_id": "string"
      },
      "course_id": "string",
      "due_on": "string",
      "source": "qms",
      "external_system": "qms",
      "external_ref": "NCR-0381"
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/lms/assignments");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"employee":{"odoo_employee_id":"string","rivetit_id":"string"},"course_id":"string","due_on":"string","source":"qms","external_system":"qms","external_ref":"NCR-0381"}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Existing assignment reused (or idempotent replay of a 200)

FieldTypeDescription
data object
data.id string
data.employee object
data.employee.rivetit_id string
data.employee.odoo_employee_id string
data.course_id string
data.course_revision integer
data.status string (open | completed | waived | cancelled)
data.overdue boolean
data.required boolean
data.reason string
data.due_on string (date)
data.original_due_on string (date)
data.external_system string
data.external_ref string
data.completion_id string
data.created_at string (date-time)
data.closed_at string (date-time)
data.close_reason string
data.updated_at string (date-time)
data.revision integer
data.reused boolean
data.source string Echo of the request's source
Example response
json
{
    "data": {
        "id": "asg_123",
        "employee": {
            "rivetit_id": "string",
            "odoo_employee_id": "string"
        },
        "course_id": "string",
        "course_revision": 1,
        "status": "open",
        "overdue": true,
        "required": true,
        "reason": "string",
        "due_on": "string",
        "original_due_on": "string",
        "external_system": "string",
        "external_ref": "string",
        "completion_id": "string",
        "created_at": "2026-01-01T09:00:00Z",
        "closed_at": "2026-01-01T09:00:00Z",
        "close_reason": "string",
        "updated_at": "2026-01-01T09:00:00Z",
        "revision": 1,
        "reused": true,
        "source": "string"
    }
}

201Assignment created

FieldTypeDescription
data object
data.id string
data.employee object
data.employee.rivetit_id string
data.employee.odoo_employee_id string
data.course_id string
data.course_revision integer
data.status string (open | completed | waived | cancelled)
data.overdue boolean
data.required boolean
data.reason string
data.due_on string (date)
data.original_due_on string (date)
data.external_system string
data.external_ref string
data.completion_id string
data.created_at string (date-time)
data.closed_at string (date-time)
data.close_reason string
data.updated_at string (date-time)
data.revision integer
data.reused boolean
data.source string Echo of the request's source
Example response
json
{
    "data": {
        "id": "asg_123",
        "employee": {
            "rivetit_id": "string",
            "odoo_employee_id": "string"
        },
        "course_id": "string",
        "course_revision": 1,
        "status": "open",
        "overdue": true,
        "required": true,
        "reason": "string",
        "due_on": "string",
        "original_due_on": "string",
        "external_system": "string",
        "external_ref": "string",
        "completion_id": "string",
        "created_at": "2026-01-01T09:00:00Z",
        "closed_at": "2026-01-01T09:00:00Z",
        "close_reason": "string",
        "updated_at": "2026-01-01T09:00:00Z",
        "revision": 1,
        "reused": true,
        "source": "string"
    }
}

400invalid_limit, invalid_cursor, invalid_updated_since, invalid_department_id, invalid_odoo_employee_id, invalid_status, invalid_json, idempotency_key_required or idempotency_key_invalid

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

409external_ref_conflict, assignment_waived, already_current or idempotency_in_progress

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

422Validation: invalid_employee, employee_not_found, employee_ambiguous, employee_mismatch, employee_not_eligible, course_not_found, course_not_published, invalid_due_on, due_on_in_past, idempotency_key_reuse, ...

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /lms/assignments/{id} Bearer token or API key

One assignment

Scope lms:read. id looks like asg_123. An assignment of a person outside the client's department scope is the same 404 as an unknown id.

Parameters

NameInTypeDescription
idrequiredpathstring

Example request

curl "https://YOUR-HOST/api/v1/lms/assignments/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/lms/assignments/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/lms/assignments/1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/lms/assignments/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Assignment

FieldTypeDescription
data object
data.id string
data.employee object
data.employee.rivetit_id string
data.employee.odoo_employee_id string
data.course_id string
data.course_revision integer
data.status string (open | completed | waived | cancelled)
data.overdue boolean
data.required boolean
data.reason string
data.due_on string (date)
data.original_due_on string (date)
data.external_system string
data.external_ref string
data.completion_id string
data.created_at string (date-time)
data.closed_at string (date-time)
data.close_reason string
data.updated_at string (date-time)
data.revision integer
Example response
json
{
    "data": {
        "id": "asg_123",
        "employee": {
            "rivetit_id": "string",
            "odoo_employee_id": "string"
        },
        "course_id": "string",
        "course_revision": 1,
        "status": "open",
        "overdue": true,
        "required": true,
        "reason": "string",
        "due_on": "string",
        "original_due_on": "string",
        "external_system": "string",
        "external_ref": "string",
        "completion_id": "string",
        "created_at": "2026-01-01T09:00:00Z",
        "closed_at": "2026-01-01T09:00:00Z",
        "close_reason": "string",
        "updated_at": "2026-01-01T09:00:00Z",
        "revision": 1
    }
}

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

404not_found (unknown, unpublished or not servable; the two are not distinguished)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /lms/completions Bearer token or API key

List completions

Scope lms:completions:read. Completion records are never deleted; a corrected record is voided or superseded and stays listed. Filters employee, odoo_employee_id, course, assignment, status (completed, voided, superseded), updated_since.

Parameters

NameInTypeDescription
limitqueryinteger
cursorquerystringOpaque `next_cursor` from the previous page
updated_sincequerystring (date-time)RFC 3339 timestamp; only records changed at or after it
employeequerystring
odoo_employee_idquerystring
coursequerystring
assignmentquerystring
statusquerystring (completed | voided | superseded)

Example request

curl "https://YOUR-HOST/api/v1/lms/completions" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/lms/completions",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/lms/completions", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/lms/completions");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Completions

FieldTypeDescription
data array of object
data[].id string
data[].employee object
data[].employee.rivetit_id string
data[].employee.odoo_employee_id string
data[].course_id string
data[].course_revision integer
data[].course_revision_id integer
data[].assignment_id string
data[].assignment object
data[].assignment.external_system string
data[].assignment.external_ref string
data[].completed_on string (date)
data[].result string (passed)
data[].score_pct number
data[].pass_mark_pct integer
data[].method string
data[].status string (completed | voided | superseded)
data[].supersedes_id string
data[].expires_on string (date) Recertification date
data[].evidence_ref object
data[].evidence_ref.certificate_number string
data[].evidence_ref.external_issuer string
data[].evidence_ref.external_ref string
data[].evidence_ref.evidence_available boolean
data[].evidence_ref.evidence_path string
data[].recorded_at string (date-time)
data[].updated_at string (date-time)
data[].revision integer
next_cursor string
Example response
json
{
    "data": [
        {
            "id": "cmp_123",
            "employee": {
                "rivetit_id": null,
                "odoo_employee_id": null
            },
            "course_id": "string",
            "course_revision": 1,
            "course_revision_id": 1,
            "assignment_id": "string",
            "assignment": {
                "external_system": null,
                "external_ref": null
            },
            "completed_on": "string",
            "result": "passed",
            "score_pct": 1.5,
            "pass_mark_pct": 1,
            "method": "string",
            "status": "completed",
            "supersedes_id": "string",
            "expires_on": "string",
            "evidence_ref": {
                "certificate_number": null,
                "external_issuer": null,
                "external_ref": null,
                "evidence_available": null,
                "evidence_path": null
            },
            "recorded_at": "2026-01-01T09:00:00Z",
            "updated_at": "2026-01-01T09:00:00Z",
            "revision": 1
        }
    ],
    "next_cursor": "string"
}

400invalid_limit, invalid_cursor, invalid_updated_since, invalid_department_id, invalid_odoo_employee_id, invalid_status, invalid_json, idempotency_key_required or idempotency_key_invalid

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /lms/completions/{id} Bearer token or API key

One completion

Scope lms:completions:read. id looks like cmp_123. A completion of a person outside the client's department scope is the same 404 as an unknown id.

Parameters

NameInTypeDescription
idrequiredpathstring

Example request

curl "https://YOUR-HOST/api/v1/lms/completions/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/lms/completions/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/lms/completions/1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/lms/completions/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Completion

FieldTypeDescription
data object
data.id string
data.employee object
data.employee.rivetit_id string
data.employee.odoo_employee_id string
data.course_id string
data.course_revision integer
data.course_revision_id integer
data.assignment_id string
data.assignment object
data.assignment.external_system string
data.assignment.external_ref string
data.completed_on string (date)
data.result string (passed)
data.score_pct number
data.pass_mark_pct integer
data.method string
data.status string (completed | voided | superseded)
data.supersedes_id string
data.expires_on string (date) Recertification date
data.evidence_ref object
data.evidence_ref.certificate_number string
data.evidence_ref.external_issuer string
data.evidence_ref.external_ref string
data.evidence_ref.evidence_available boolean
data.evidence_ref.evidence_path string
data.recorded_at string (date-time)
data.updated_at string (date-time)
data.revision integer
Example response
json
{
    "data": {
        "id": "cmp_123",
        "employee": {
            "rivetit_id": "string",
            "odoo_employee_id": "string"
        },
        "course_id": "string",
        "course_revision": 1,
        "course_revision_id": 1,
        "assignment_id": "string",
        "assignment": {
            "external_system": "string",
            "external_ref": "string"
        },
        "completed_on": "string",
        "result": "passed",
        "score_pct": 1.5,
        "pass_mark_pct": 1,
        "method": "string",
        "status": "completed",
        "supersedes_id": "string",
        "expires_on": "string",
        "evidence_ref": {
            "certificate_number": "string",
            "external_issuer": "string",
            "external_ref": "string",
            "evidence_available": true,
            "evidence_path": "string"
        },
        "recorded_at": "2026-01-01T09:00:00Z",
        "updated_at": "2026-01-01T09:00:00Z",
        "revision": 1
    }
}

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

404not_found (unknown, unpublished or not servable; the two are not distinguished)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /lms/completions/{id}/evidence Bearer token or API key

The completion's evidence file

Scope lms:evidence:read. Streamed through the API after the same visibility check the web endpoint applies (the file must be referenced by the completion). 404 when there is no file or it may not be served.

Parameters

NameInTypeDescription
idrequiredpathstring

Example request

curl "https://YOUR-HOST/api/v1/lms/completions/1/evidence" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/lms/completions/1/evidence",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/lms/completions/1/evidence", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/lms/completions/1/evidence");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200The file (PDF, JPEG or PNG), as an attachment

Example response
json
"string"

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

404not_found (unknown, unpublished or not servable; the two are not distinguished)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /employees Bearer token or API key

Employee directory

Scope directory:read only (no lms:* scope grants it). Employees are RivetIT contacts; the identity key for the QMS is odoo_employee_id (from the Odoo directory link; null when the person is not linked). Deactivated people stay in the feed with active: false (terminated or archived) so the QMS can deprovision them. Limited to the client's department scope: a restricted client sees only the employees of its departments; manager_id is null when the manager is outside that scope. Ascending id, cursor paging, incremental sync with updated_since. Only name, work email and job title are exposed - no phone, PIN, address or notes.

Parameters

NameInTypeDescription
limitqueryinteger
cursorquerystringOpaque `next_cursor` from the previous page
updated_sincequerystring (date-time)RFC 3339 timestamp; only records changed at or after it
department_idquerystringOnly the employees of this department (RivetIT id)
odoo_employee_idquerystring

Example request

curl "https://YOUR-HOST/api/v1/employees" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/employees",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/employees", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/employees");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Employees

FieldTypeDescription
data array of object
data[].id string RivetIT contact id
data[].odoo_employee_id string Identity key: the Odoo employee id from the directory link
data[].name string
data[].work_email string
data[].job_title string
data[].department_id string RivetIT department id (null = no department)
data[].odoo_department_id string
data[].manager_id string Null when there is no manager or the manager is outside the client's department scope
data[].employment_status string pre-hire, active, leave, suspended, transfer_pending, termination_pending, terminated or archived
data[].active boolean false for terminated or archived people (tombstones): deprovision them
data[].updated_at string (date-time)
next_cursor string
Example response
json
{
    "data": [
        {
            "id": "string",
            "odoo_employee_id": "string",
            "name": "string",
            "work_email": "string",
            "job_title": "string",
            "department_id": "string",
            "odoo_department_id": "string",
            "manager_id": "string",
            "employment_status": "string",
            "active": true,
            "updated_at": "2026-01-01T09:00:00Z"
        }
    ],
    "next_cursor": "string"
}

400invalid_limit, invalid_cursor, invalid_updated_since, invalid_department_id, invalid_odoo_employee_id, invalid_status, invalid_json, idempotency_key_required or idempotency_key_invalid

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /employees/{id} Bearer token or API key

One employee

Scope directory:read. id is the RivetIT id from the list. Unknown, malformed and out-of-department-scope ids are all the same 404. A deactivated employee is returned with active set to false.

Parameters

NameInTypeDescription
idrequiredpathstring

Example request

curl "https://YOUR-HOST/api/v1/employees/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/employees/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/employees/1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/employees/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Employee

FieldTypeDescription
data object
data.id string RivetIT contact id
data.odoo_employee_id string Identity key: the Odoo employee id from the directory link
data.name string
data.work_email string
data.job_title string
data.department_id string RivetIT department id (null = no department)
data.odoo_department_id string
data.manager_id string Null when there is no manager or the manager is outside the client's department scope
data.employment_status string pre-hire, active, leave, suspended, transfer_pending, termination_pending, terminated or archived
data.active boolean false for terminated or archived people (tombstones): deprovision them
data.updated_at string (date-time)
Example response
json
{
    "data": {
        "id": "string",
        "odoo_employee_id": "string",
        "name": "string",
        "work_email": "string",
        "job_title": "string",
        "department_id": "string",
        "odoo_department_id": "string",
        "manager_id": "string",
        "employment_status": "string",
        "active": true,
        "updated_at": "2026-01-01T09:00:00Z"
    }
}

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

404not_found (unknown, unpublished or not servable; the two are not distinguished)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /departments Bearer token or API key

Department directory

Scope directory:read only. Departments are RivetIT clients (CRM leads are not departments). Archived and inactive departments stay in the feed (active: false). Limited to the client's department scope; parent_id and head_employee_id are null when they point outside it. Ascending id, cursor paging, incremental sync with updated_since.

Parameters

NameInTypeDescription
limitqueryinteger
cursorquerystringOpaque `next_cursor` from the previous page
updated_sincequerystring (date-time)RFC 3339 timestamp; only records changed at or after it

Example request

curl "https://YOUR-HOST/api/v1/departments" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/departments",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/departments", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/departments");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Departments

FieldTypeDescription
data array of object
data[].id string RivetIT department (client) id
data[].odoo_department_id string
data[].name string
data[].parent_id string Null when there is no parent or it is outside the client's department scope
data[].head_employee_id string Null when there is no head or the head is outside the client's department scope
data[].status string active, inactive, on_hold or archived
data[].active boolean false when archived or inactive (tombstone)
data[].updated_at string (date-time)
next_cursor string
Example response
json
{
    "data": [
        {
            "id": "string",
            "odoo_department_id": "string",
            "name": "string",
            "parent_id": "string",
            "head_employee_id": "string",
            "status": "string",
            "active": true,
            "updated_at": "2026-01-01T09:00:00Z"
        }
    ],
    "next_cursor": "string"
}

400invalid_limit, invalid_cursor, invalid_updated_since, invalid_department_id, invalid_odoo_employee_id, invalid_status, invalid_json, idempotency_key_required or idempotency_key_invalid

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated
GET /departments/{id} Bearer token or API key

One department

Scope directory:read. Unknown, malformed and out-of-department-scope ids are all the same 404.

Parameters

NameInTypeDescription
idrequiredpathstring

Example request

curl "https://YOUR-HOST/api/v1/departments/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/departments/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/departments/1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/departments/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Department

FieldTypeDescription
data object
data.id string RivetIT department (client) id
data.odoo_department_id string
data.name string
data.parent_id string Null when there is no parent or it is outside the client's department scope
data.head_employee_id string Null when there is no head or the head is outside the client's department scope
data.status string active, inactive, on_hold or archived
data.active boolean false when archived or inactive (tombstone)
data.updated_at string (date-time)
Example response
json
{
    "data": {
        "id": "string",
        "odoo_department_id": "string",
        "name": "string",
        "parent_id": "string",
        "head_employee_id": "string",
        "status": "string",
        "active": true,
        "updated_at": "2026-01-01T09:00:00Z"
    }
}

401invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

403insufficient_scope (the token does not carry the scope the route needs)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated

404not_found (unknown, unpublished or not servable; the two are not distinguished)

FieldTypeDescription
error object
error.code string
error.message string
error.correlation_id string Echo of X-Correlation-Id, or generated