Documents

Base paths: /api/v1/documents and /api/v2/documents

A document represents a procedure, guide, contract, report or similar artefact registered in OS2compliance.

v1 vs. v2 — which should I use?

There are two versions of the documents resource. They are identical except for how the document type is expressed:

  v1 (/api/v1/documents) v2 (/api/v2/documents)
Document type field documentType — a fixed enum documentTypeIdentifier — a choice-value identifier (string)
Allowed values PROCEDURE, GUIDE, WORKFLOW, CONTRACT, DATA_PROCESSING_AGREEMENT, SUPERVISORY_REPORT, MANAGEMENT_REPORT, RISK_ASSESSMENT_REPORT, CONTROL, OTHER Any document-type identifier configured in OS2compliance, e.g. document-type-procedure-123456
Custom document types Not supported (fixed list only) Supported

Use v2 for new integrations — it supports custom document types configured in the installation. v1 remains for backwards compatibility and maps its fixed enum onto the corresponding built-in choice values.

Endpoints

The two versions expose the same set of operations; substitute v1 or v2 in the path.

Method Path Description
GET /api/{v1,v2}/documents List all documents (paged)
GET /api/{v1,v2}/documents/{id} Fetch a single document
POST /api/{v1,v2}/documents Create a new document
PUT /api/{v1,v2}/documents/{id} Update an existing document
DELETE /api/{v1,v2}/documents/{id} Delete a document

List

GET /api/v2/documents — query parameters page (default 0), pageSize (default 100, max 500). Returns a page of Document objects. 200 OK · 401 Unauthorized.

Fetch

GET /api/v2/documents/{id} — 200 OK · 404 Not Found · 401 Unauthorized.

Create

POST /api/v2/documents — body is a Document create payload. Returns the created document. 201 Created · 400 Bad Request (invalid document type identifier) · 401 Unauthorized.

Update

PUT /api/v2/documents/{id} — read-modify-write; the version must match the current version. Send the complete entity back. 204 No Content · 404 Not Found · 401 Unauthorized · 409 Conflict (version mismatch) · 400 Bad Request (invalid document type identifier).

Delete

DELETE /api/v2/documents/{id} — 204 No Content · 404 Not Found · 401 Unauthorized.


The Document object (v2)

Field Type Notes
version integer Required on update; must match current version
name string Required
responsibleUser User On write, send { "uuid": "..." }
status enum Required. NOT_STARTED, IN_PROGRESS, READY
documentTypeIdentifier string Required. A document-type choice-value identifier, e.g. document-type-procedure-123456
description string  
link string Link to the document, e.g. http://someurl.com/filename.doc
documentVersion string The document’s own version label, e.g. 1.2b
revisionInterval enum NONE, HALF_YEARLY, YEARLY, EVERY_SECOND_YEAR, EVERY_THIRD_YEAR
nextRevision date  
includeInYearWheel boolean Update only — include the revision in the year wheel

The Document object (v1)

Identical to v2 except that the document type is the fixed enum field documentType (values listed in the table above) instead of documentTypeIdentifier.

Example — create request (v2)

{
  "name": "Databehandleraftale-procedure",
  "responsibleUser": { "uuid": "f2dad6d3-79a3-426b-986f-ac568d759983" },
  "status": "IN_PROGRESS",
  "documentTypeIdentifier": "document-type-procedure-123456",
  "description": "En beskrivelse af dokumentet",
  "link": "http://someurl.com/filename.doc",
  "documentVersion": "1.2b",
  "revisionInterval": "EVERY_SECOND_YEAR"
}

Example — create request (v1)

{
  "name": "Databehandleraftale-procedure",
  "responsibleUser": { "uuid": "f2dad6d3-79a3-426b-986f-ac568d759983" },
  "status": "IN_PROGRESS",
  "documentType": "GUIDE",
  "description": "En beskrivelse af dokumentet",
  "link": "http://someurl.com/filename.doc",
  "documentVersion": "1.2b",
  "revisionInterval": "EVERY_SECOND_YEAR"
}

This site uses Just the Docs, a documentation theme for Jekyll.