Documents API

25 endpoints, generated from packages/core/openapi/v1.snapshot.json (OpenAPI 3.1.0, contract version 1.0). Conventions for lists, errors, money and authentication are on the API conventions page.

GET/api/v1/documents

Documents the member may see (`mine=true`, `employeeId`, `categoryId`, `expiry`)

Access

Permission documents:read

Parameters

Name	In	Type	Required
employeeId	query	string (uuid)	no
categoryId	query	string (uuid)	no
mine	query	enum	no
expiry	query	enum	no
deleted	query	enum	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • employeeIdstring (uuid)required
  • employeeNamestringrequired
  • employeeNumberstringrequired
  • categoryobjectrequired

    • idstring (uuid)required
    • namestringrequired
    • sensitivityenumrequired

      one of "normal", "medical"

  • titlestringrequired
  • notesstring | nullrequired
  • expiresOnstring | nullrequired
  • expiryenum or nullrequired

    one of "valid", "expiring", "expired"

  • sourceenumrequired

    one of "upload", "generated"

  • currentobject or nullrequired

    • idstring (uuid)required
    • versionintegerrequired

      min -9007199254740991

    • fileNamestring | nullrequired
    • mimestring | nullrequired
    • sizeBytesinteger or nullrequired

      min -9007199254740991

    • sha256stringrequired
    • expiresOnstring | nullrequired
    • sourceenumrequired

      one of "upload", "generated"

    • templateIdstring (uuid) or nullrequired
    • templateVersioninteger or nullrequired

      min -9007199254740991

    • asAtstring | nullrequired
    • createdAtstringrequired
    • supersededbooleanrequired
  • previousVersionsarray of objectrequired

    Superseded versions (HR only).

    • idstring (uuid)required
    • versionintegerrequired

      min -9007199254740991

    • fileNamestring | nullrequired
    • mimestring | nullrequired
    • sizeBytesinteger or nullrequired

      min -9007199254740991

    • sha256stringrequired
    • expiresOnstring | nullrequired
    • sourceenumrequired

      one of "upload", "generated"

    • templateIdstring (uuid) or nullrequired
    • templateVersioninteger or nullrequired

      min -9007199254740991

    • asAtstring | nullrequired
    • createdAtstringrequired
    • supersededbooleanrequired
  • acknowledgementobject or nullrequired

    • idstring (uuid)required
    • statusenumrequired

      one of "requested", "acknowledged"

    • requestedAtstringrequired
    • acknowledgedAtstring | nullrequired
    • fileSha256string | nullrequired
    • currentbooleanrequired

      False when a newer version needs a new acknowledgement.

  • viewedbooleanrequired
  • createdAtstringrequired
  • deletedAtstring | nullrequired
  • canManagebooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/documents/{id}

A document with its versions and acknowledgement

Access

Permission documents:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• employeeNamestringrequired
• employeeNumberstringrequired
• categoryobjectrequired

  • idstring (uuid)required
  • namestringrequired
  • sensitivityenumrequired

    one of "normal", "medical"

• titlestringrequired
• notesstring | nullrequired
• expiresOnstring | nullrequired
• expiryenum or nullrequired

  one of "valid", "expiring", "expired"

• sourceenumrequired

  one of "upload", "generated"

• currentobject or nullrequired

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• previousVersionsarray of objectrequired

  Superseded versions (HR only).

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• acknowledgementobject or nullrequired

  • idstring (uuid)required
  • statusenumrequired

    one of "requested", "acknowledged"

  • requestedAtstringrequired
  • acknowledgedAtstring | nullrequired
  • fileSha256string | nullrequired
  • currentbooleanrequired

    False when a newer version needs a new acknowledgement.

• viewedbooleanrequired
• createdAtstringrequired
• deletedAtstring | nullrequired
• canManagebooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

PATCH/api/v1/documents/{id}

Rename, re-note or re-file a document

Access

Permission documents:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• titlestring

  min length 1 · max length 120

• notesstring or null

  max length 1000

• categoryIdstring (uuid)

Responses

200 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• employeeNamestringrequired
• employeeNumberstringrequired
• categoryobjectrequired

  • idstring (uuid)required
  • namestringrequired
  • sensitivityenumrequired

    one of "normal", "medical"

• titlestringrequired
• notesstring | nullrequired
• expiresOnstring | nullrequired
• expiryenum or nullrequired

  one of "valid", "expiring", "expired"

• sourceenumrequired

  one of "upload", "generated"

• currentobject or nullrequired

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• previousVersionsarray of objectrequired

  Superseded versions (HR only).

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• acknowledgementobject or nullrequired

  • idstring (uuid)required
  • statusenumrequired

    one of "requested", "acknowledged"

  • requestedAtstringrequired
  • acknowledgedAtstring | nullrequired
  • fileSha256string | nullrequired
  • currentbooleanrequired

    False when a newer version needs a new acknowledgement.

• viewedbooleanrequired
• createdAtstringrequired
• deletedAtstring | nullrequired
• canManagebooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required

DELETE/api/v1/documents/{id}

Delete a document (soft: hidden, kept and audited)

Access

Permission documents:delete

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes
reason	query	string	no

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required

POST/api/v1/documents/{id}/acknowledge

Acknowledge the document (employee; open it first). Records time, IP, user agent and the file's SHA-256

Access

Permission documents:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• employeeNamestringrequired
• employeeNumberstringrequired
• categoryobjectrequired

  • idstring (uuid)required
  • namestringrequired
  • sensitivityenumrequired

    one of "normal", "medical"

• titlestringrequired
• notesstring | nullrequired
• expiresOnstring | nullrequired
• expiryenum or nullrequired

  one of "valid", "expiring", "expired"

• sourceenumrequired

  one of "upload", "generated"

• currentobject or nullrequired

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• previousVersionsarray of objectrequired

  Superseded versions (HR only).

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• acknowledgementobject or nullrequired

  • idstring (uuid)required
  • statusenumrequired

    one of "requested", "acknowledged"

  • requestedAtstringrequired
  • acknowledgedAtstring | nullrequired
  • fileSha256string | nullrequired
  • currentbooleanrequired

    False when a newer version needs a new acknowledgement.

• viewedbooleanrequired
• createdAtstringrequired
• deletedAtstring | nullrequired
• canManagebooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 409 conflict, not_viewed

POST/api/v1/documents/{id}/acknowledgements

Ask the employee to read and acknowledge the current version

Access

Permission documents:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• employeeNamestringrequired
• employeeNumberstringrequired
• categoryobjectrequired

  • idstring (uuid)required
  • namestringrequired
  • sensitivityenumrequired

    one of "normal", "medical"

• titlestringrequired
• notesstring | nullrequired
• expiresOnstring | nullrequired
• expiryenum or nullrequired

  one of "valid", "expiring", "expired"

• sourceenumrequired

  one of "upload", "generated"

• currentobject or nullrequired

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• previousVersionsarray of objectrequired

  Superseded versions (HR only).

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• acknowledgementobject or nullrequired

  • idstring (uuid)required
  • statusenumrequired

    one of "requested", "acknowledged"

  • requestedAtstringrequired
  • acknowledgedAtstring | nullrequired
  • fileSha256string | nullrequired
  • currentbooleanrequired

    False when a newer version needs a new acknowledgement.

• viewedbooleanrequired
• createdAtstringrequired
• deletedAtstring | nullrequired
• canManagebooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 409 conflict

GET/api/v1/documents/{id}/file

Download (or view) the document; records the first view and audits medical and identity views

Served with the detected type, `Content-Disposition: attachment` (images and PDFs may be viewed inline with `inline=1`), `X-Content-Type-Options: nosniff` and a sandbox CSP. 404 for anyone who may not see it.

Access

Permission documents:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes
version	query	string (uuid)	no
inline	query	enum	no

Responses

200 The file application/octet-stream

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/documents/{id}/purge

Permanently remove a deleted document and its files (owners only)

Access

Permission documents:delete

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• reasonstringrequired

  min length 1 · max length 300

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, reauth_required
• 409 conflict

POST/api/v1/documents/{id}/versions

Replace the file (raw bytes in the body): a new version; the old one is kept for HR

Access

Permission documents:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes
expiresOn	query	string	no
fileName	query	string	no

Responses

201 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• employeeNamestringrequired
• employeeNumberstringrequired
• categoryobjectrequired

  • idstring (uuid)required
  • namestringrequired
  • sensitivityenumrequired

    one of "normal", "medical"

• titlestringrequired
• notesstring | nullrequired
• expiresOnstring | nullrequired
• expiryenum or nullrequired

  one of "valid", "expiring", "expired"

• sourceenumrequired

  one of "upload", "generated"

• currentobject or nullrequired

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• previousVersionsarray of objectrequired

  Superseded versions (HR only).

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• acknowledgementobject or nullrequired

  • idstring (uuid)required
  • statusenumrequired

    one of "requested", "acknowledged"

  • requestedAtstringrequired
  • acknowledgedAtstring | nullrequired
  • fileSha256string | nullrequired
  • currentbooleanrequired

    False when a newer version needs a new acknowledgement.

• viewedbooleanrequired
• createdAtstringrequired
• deletedAtstring | nullrequired
• canManagebooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 413 file_too_large
• 415 unsupported_file_type

GET/api/v1/documents/acknowledgements

Outstanding and completed acknowledgements (`format=csv` to download)

Access

Permission documents:update

Parameters

Name	In	Type	Required
status	query	enum	no
documentId	query	string (uuid)	no
employeeId	query	string (uuid)	no
format	query	enum	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • documentIdstring (uuid)required
  • documentTitlestringrequired
  • employeeIdstring (uuid)required
  • employeeNamestringrequired
  • employeeNumberstringrequired
  • versionintegerrequired

    min -9007199254740991

  • requestedAtstringrequired
  • acknowledgedAtstring | nullrequired
  • fileSha256string | nullrequired
  • ipstring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/documents/categories

Document categories with their access flags

Access

Permission documents:read

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • systemKeystring | nullrequired
  • namestringrequired
  • sensitivityenumrequired

    one of "normal", "medical"

  • employeeVisiblebooleanrequired
  • managerVisiblebooleanrequired
  • payrollVisiblebooleanrequired
  • employeeUploadablebooleanrequired
  • expiryRequiredbooleanrequired
  • auditViewsbooleanrequired
  • retentionMonthsAfterExitinteger or nullrequired

    min -9007199254740991

  • positionintegerrequired

    min -9007199254740991

  • documentCountintegerrequired

    min -9007199254740991

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

POST/api/v1/documents/categories

Add a document category

Access

Permission documents:update

Request body

application/json, object, required

• namestringrequired

  min length 1 · max length 60

• sensitivityenum

  one of "normal", "medical" · default "normal"

• employeeVisibleboolean

  default false

• managerVisibleboolean

  default false

• payrollVisibleboolean

  default false

• employeeUploadableboolean

  default false

• expiryRequiredboolean

  default false

• auditViewsboolean

  default false

• retentionMonthsAfterExitinteger or null

  min 0 · max 1200

Responses

201 Success. object

• idstring (uuid)required
• systemKeystring | nullrequired
• namestringrequired
• sensitivityenumrequired

  one of "normal", "medical"

• employeeVisiblebooleanrequired
• managerVisiblebooleanrequired
• payrollVisiblebooleanrequired
• employeeUploadablebooleanrequired
• expiryRequiredbooleanrequired
• auditViewsbooleanrequired
• retentionMonthsAfterExitinteger or nullrequired

  min -9007199254740991

• positionintegerrequired

  min -9007199254740991

• documentCountintegerrequired

  min -9007199254740991

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 409 conflict

PATCH/api/v1/documents/categories/{id}

Change a category (medical categories can't be visible to managers)

Access

Permission documents:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• namestring

  min length 1 · max length 60

• sensitivityenum

  one of "normal", "medical"

• employeeVisibleboolean
• managerVisibleboolean
• payrollVisibleboolean
• employeeUploadableboolean
• expiryRequiredboolean
• auditViewsboolean
• retentionMonthsAfterExitinteger or null

  min 0 · max 1200

Responses

200 Success. object

• idstring (uuid)required
• systemKeystring | nullrequired
• namestringrequired
• sensitivityenumrequired

  one of "normal", "medical"

• employeeVisiblebooleanrequired
• managerVisiblebooleanrequired
• payrollVisiblebooleanrequired
• employeeUploadablebooleanrequired
• expiryRequiredbooleanrequired
• auditViewsbooleanrequired
• retentionMonthsAfterExitinteger or nullrequired

  min -9007199254740991

• positionintegerrequired

  min -9007199254740991

• documentCountintegerrequired

  min -9007199254740991

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required

DELETE/api/v1/documents/categories/{id}

Delete an empty category

Access

Permission documents:delete

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 409 in_use

GET/api/v1/documents/fields

The merge fields a letter template may use

Access

Permission documents:update

Responses

200 Success. object

• itemsarray of objectrequired

  • idstringrequired
  • labelstringrequired
  • groupstringrequired
  • sensitivitystring
  • wherestringrequired
  • perDocumentboolean

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

POST/api/v1/documents/generate

Generate a letter from a template for an employee (or preview it with `dryRun`)

Every merge field is resolved as at `asAt`. Missing values block generation (422 `missing_fields`, with where to fill each). Templates with salary fields need salary read for the employee (403 otherwise).

Access

Permission documents:update

Request body

application/json, object, required

• templateIdstring (uuid)required
• employeeIdstring (uuid)required
• asAtstring
• titlestring

  min length 1 · max length 120

• signatoryNamestring

  min length 1 · max length 120

• overridesobject

  default {}

• requestAcknowledgementboolean

  default false

• dryRunboolean

  default false

Responses

200 Success. object

• documentIdstring (uuid) or nullrequired
• missingarray of objectrequired

  • idstringrequired
  • labelstringrequired
  • wherestringrequired
• valuesobjectrequired
• blocksarray of objectrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 422 missing_fields

GET/api/v1/documents/requests

My letter requests

Access

Any signed-in member (own data only)

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • kindenumrequired

    one of "offer", "ket", "confirmation", "promotion", "salary_adjustment", "resignation_acceptance", "employment_certificate", "custom"

  • purposestring | nullrequired
  • statusenumrequired

    one of "pending", "approved", "rejected", "withdrawn"

  • documentIdstring (uuid) or nullrequired
  • createdAtstringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

POST/api/v1/documents/requests

Ask HR for an employment letter; on approval it is generated and filed in your documents

Access

Any signed-in member (own data only)

Request body

application/json, object, required

• kind"employment_certificate"required
• purposestringrequired

  min length 1 · max length 200

Responses

201 Success. object

• idstring (uuid)required
• status"pending"required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required

GET/api/v1/documents/retention

Documents flagged for a retention review (nothing is deleted without a decision)

Access

Permission documents:update

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • documentIdstring (uuid)required
  • documentTitlestringrequired
  • categorystringrequired
  • employeeIdstring (uuid)required
  • employeeNamestringrequired
  • reasonstringrequired
  • reviewFromstringrequired
  • flaggedAtstringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

POST/api/v1/documents/retention/{id}/resolve

Keep a flagged document for longer, or delete it (soft; an owner can then purge it)

Access

Permission documents:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object | object, required

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 409 already_decided

GET/api/v1/documents/templates

Letter templates

Access

Permission documents:update

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • kindenumrequired

    one of "offer", "ket", "confirmation", "promotion", "salary_adjustment", "resignation_acceptance", "employment_certificate", "custom"

  • namestringrequired
  • bodyMdstringrequired
  • versionintegerrequired

    min -9007199254740991

  • activebooleanrequired
  • targetCategoryIdstring (uuid)required
  • fieldsarray of stringrequired
  • usesSalarybooleanrequired
  • updatedAtstringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

POST/api/v1/documents/templates

Create a letter template

Access

Permission documents:update

Request body

application/json, object, required

• kindenumrequired

  one of "offer", "ket", "confirmation", "promotion", "salary_adjustment", "resignation_acceptance", "employment_certificate", "custom"

• namestringrequired

  min length 1 · max length 80

• bodyMdstringrequired

  max length 50000

• targetCategoryIdstring (uuid)
• activeboolean

  default true

Responses

201 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "offer", "ket", "confirmation", "promotion", "salary_adjustment", "resignation_acceptance", "employment_certificate", "custom"

• namestringrequired
• bodyMdstringrequired
• versionintegerrequired

  min -9007199254740991

• activebooleanrequired
• targetCategoryIdstring (uuid)required
• fieldsarray of stringrequired
• usesSalarybooleanrequired
• updatedAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 409 conflict

PUT/api/v1/documents/templates/{id}

Update a letter template (a new version)

Access

Permission documents:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• kindenum

  one of "offer", "ket", "confirmation", "promotion", "salary_adjustment", "resignation_acceptance", "employment_certificate", "custom"

• namestring

  min length 1 · max length 80

• bodyMdstring

  max length 50000

• targetCategoryIdstring (uuid)
• activeboolean

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "offer", "ket", "confirmation", "promotion", "salary_adjustment", "resignation_acceptance", "employment_certificate", "custom"

• namestringrequired
• bodyMdstringrequired
• versionintegerrequired

  min -9007199254740991

• activebooleanrequired
• targetCategoryIdstring (uuid)required
• fieldsarray of stringrequired
• usesSalarybooleanrequired
• updatedAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required

POST/api/v1/documents/templates/check

Check a template body without saving: unknown fields, disallowed Markdown, KET items

Access

Permission documents:update

Request body

application/json, object, required

• kindenumrequired

  one of "offer", "ket", "confirmation", "promotion", "salary_adjustment", "resignation_acceptance", "employment_certificate", "custom"

• bodyMdstringrequired

  max length 50000

Responses

200 Success. object

• issuesarray of objectrequired

  • lineintegerrequired

    min -9007199254740991

  • messagestringrequired
• fieldsarray of stringrequired
• blocksarray of objectrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required

POST/api/v1/documents/upload

Upload a document for an employee (raw bytes in the body; PDF, JPEG, PNG, WebP, DOCX or XLSX, at most 20 MB)

The file type is detected from its content. DOCX and XLSX must be valid OOXML packages; macro-enabled files are refused. Employees may upload only to their own employee-uploadable categories.

Access

Permission documents:create

Parameters

Name	In	Type	Required
employeeId	query	string (uuid)	yes
categoryId	query	string (uuid)	yes
title	query	string	yes
expiresOn	query	string	no
notes	query	string	no
fileName	query	string	no

Responses

201 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• employeeNamestringrequired
• employeeNumberstringrequired
• categoryobjectrequired

  • idstring (uuid)required
  • namestringrequired
  • sensitivityenumrequired

    one of "normal", "medical"

• titlestringrequired
• notesstring | nullrequired
• expiresOnstring | nullrequired
• expiryenum or nullrequired

  one of "valid", "expiring", "expired"

• sourceenumrequired

  one of "upload", "generated"

• currentobject or nullrequired

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• previousVersionsarray of objectrequired

  Superseded versions (HR only).

  • idstring (uuid)required
  • versionintegerrequired

    min -9007199254740991

  • fileNamestring | nullrequired
  • mimestring | nullrequired
  • sizeBytesinteger or nullrequired

    min -9007199254740991

  • sha256stringrequired
  • expiresOnstring | nullrequired
  • sourceenumrequired

    one of "upload", "generated"

  • templateIdstring (uuid) or nullrequired
  • templateVersioninteger or nullrequired

    min -9007199254740991

  • asAtstring | nullrequired
  • createdAtstringrequired
  • supersededbooleanrequired
• acknowledgementobject or nullrequired

  • idstring (uuid)required
  • statusenumrequired

    one of "requested", "acknowledged"

  • requestedAtstringrequired
  • acknowledgedAtstring | nullrequired
  • fileSha256string | nullrequired
  • currentbooleanrequired

    False when a newer version needs a new acknowledgement.

• viewedbooleanrequired
• createdAtstringrequired
• deletedAtstring | nullrequired
• canManagebooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 413 file_too_large
• 415 unsupported_file_type