Documents API

The Documents API lets you create, retrieve, update, and manage RAMS documents programmatically. This is the largest API group, covering documents, sections, hazards, COSHH assessments, and personnel.

List documents

GET /api/v1/documents

Returns a paginated list of documents in your organisation.

Query parameters:

Parameter	Type	Description
status	string	Filter by status: draft, pending_review, approved, archived
type	string	Filter by type: rams, risk_assessment, method_statement, coshh, toolbox_talk, permit, powra
project_id	uuid	Filter by project
page	int	Page number
per_page	int	Items per page (max 100)

Example:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.ramsdoc.com/api/v1/documents?status=approved&type=rams"

Response:

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "title": "RAMS — Cable Tray Installation, Building A",
      "reference": "RAMS-202603-001",
      "document_type": "rams",
      "status": "approved",
      "version": 2,
      "project_id": "...",
      "site_id": "...",
      "created_by": "...",
      "created_at": "2026-03-15T10:30:00Z",
      "updated_at": "2026-03-20T14:22:00Z"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 42 }
}

Get a document

GET /api/v1/documents/{document}

Returns a single document with all relations (sections, hazards, COSHH, personnel).

Example:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.ramsdoc.com/api/v1/documents/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"

Create a document

POST /api/v1/documents

Request body:

{
  "title": "RAMS — Scaffold Erection, Phase 2",
  "document_type": "rams",
  "project_id": "...",
  "site_id": "..."
}

Returns the created document in draft status.

Update a document

PUT /api/v1/documents/{document}

Update document metadata (title, project, site). To update content, use the sections, hazards, and COSHH endpoints below.

Document actions

Submit for review

POST /api/v1/documents/{document}/submit-review

{
  "reviewer_id": "...",
  "notes": "Ready for review — please check Section 4 controls."
}

Approve

POST /api/v1/documents/{document}/approve

{
  "notes": "Approved. Good coverage of confined space hazards."
}

Reject

POST /api/v1/documents/{document}/reject

{
  "reason": "Hazard 4 needs a rescue plan. Section 7 missing traffic management details."
}

Export

POST /api/v1/documents/{document}/export

{
  "format": "pdf"
}

Returns an export job ID. Poll GET /api/v1/exports/{export} for the download URL when complete.

Duplicate

POST /api/v1/documents/{document}/duplicate

Creates a copy of the document in draft status.

Sections

Manage the content sections within a document.

GET    /api/v1/documents/{document}/sections
POST   /api/v1/documents/{document}/sections
PUT    /api/v1/documents/{document}/sections/{id}
DELETE /api/v1/documents/{document}/sections/{id}
PUT    /api/v1/documents/{document}/sections/reorder

Hazards

Manage hazards in the risk assessment.

GET    /api/v1/documents/{document}/hazards
POST   /api/v1/documents/{document}/hazards
PUT    /api/v1/documents/{document}/hazards/{id}
DELETE /api/v1/documents/{document}/hazards/{id}
PUT    /api/v1/documents/{document}/hazards/reorder

Create hazard example:

{
  "name": "Falls from scaffold",
  "category": "work_at_height",
  "description": "Workers could fall from the 6m scaffold during erection or use.",
  "who_at_risk": "Scaffold erectors, electrical operatives",
  "severity_before": 5,
  "likelihood_before": 4,
  "controls": [
    {
      "description": "Scaffold erected by CISRS-qualified scaffolder to TG20 specification",
      "hierarchy_level": "engineering",
      "responsibility": "Scaffold supervisor"
    }
  ],
  "severity_after": 5,
  "likelihood_after": 1
}

COSHH assessments

GET    /api/v1/documents/{document}/coshh
POST   /api/v1/documents/{document}/coshh
PUT    /api/v1/documents/{document}/coshh/{id}
DELETE /api/v1/documents/{document}/coshh/{id}

Personnel

GET    /api/v1/documents/{document}/personnel
POST   /api/v1/documents/{document}/personnel
PUT    /api/v1/documents/{document}/personnel/{id}
DELETE /api/v1/documents/{document}/personnel/{id}

Version history

GET /api/v1/documents/{document}/versions

Returns all versions of the document with approval details.

Sign-offs

GET  /api/v1/documents/{document}/signoffs
POST /api/v1/documents/{document}/signoffs

Record a worker sign-off programmatically (useful for integrations with external systems).