Skip to main content
GET
/
documents
/
{localAuthority}
Get Document Metadata
curl --request GET \
  --url https://api.example.com/documents/{localAuthority}
{
  "{financialYearRange}": {
    "{language}": [
      {
        "id": "<string>",
        "fileName": "<string>",
        "financialYear": "<string>",
        "creationDate": "<string>",
        "documentName": "<string>",
        "isLatest": true
      }
    ]
  },
  "currentFiscalYear": "<string>",
  "403 Forbidden": {},
  "500 Internal Server Error": {}
}

​
Overview

This endpoint fetches document metadata from the FSS (File Storage Service) API and processes the results to group documents by financial year (April 6 - April 5) and language. Documents created within the last 30 days are flagged as “latest”.

​
Authorization

This endpoint requires authentication and authorization via the access control plugin. Required Permission: listFinanceDocuments Allowed Roles:
  • Chief Executive Officer (CEO)
  • Head of Finance (HOF)
  • Finance Officer (FO)
  • Head of Waste (HOW)
  • Waste Officer (WO)
Users without the required permission will receive a 403 Forbidden response. All requests are logged for audit purposes with the action kind DocumentsListed.

​
Path Parameters

​
localAuthority
string
required
The local authority identifier to fetch documents for

​
Response

​
{financialYearRange}
object
Documents grouped by financial year range (e.g., “2024 to 2025”)
​
{language}
array
Documents grouped by language code (e.g., “EN”, “CY”)
​
id
string
The system ID of the document
​
fileName
string
The name of the file
​
financialYear
string
The financial year of the document
​
creationDate
string
The creation date formatted as “d MMM yyyy” (e.g., “15 Jan 2024”)
​
documentName
string
Human-readable document name (e.g., “Grant letter Q1”, “Remittance letter Q2”, “Notice of assessment”)
​
isLatest
boolean
Whether the document was created within the last 30 days
​
currentFiscalYear
string
The current fiscal year from configuration

​
Error Responses

​
403 Forbidden
object
Returned when the user’s role does not have permission to list documents
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "{role} not allowed to get document list"
}
​
500 Internal Server Error
object
Returned when the FSS API request fails or an unexpected error occurs
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Error fetching file metadata"
}

​
Examples

curl -X GET "http://localhost:3001/documents/ABC123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response Example

{
  "2024 to 2025": {
    "EN": [
      {
        "id": "abc123xyz",
        "fileName": "grant_letter_q1.pdf",
        "financialYear": "2024/25",
        "creationDate": "15 Apr 2024",
        "documentName": "Grant letter Q1",
        "isLatest": false
      },
      {
        "id": "def456uvw",
        "fileName": "remittance_q2.pdf",
        "financialYear": "2024/25",
        "creationDate": "10 Jul 2024",
        "documentName": "Remittance letter Q2",
        "isLatest": false
      }
    ],
    "CY": [
      {
        "id": "ghi789rst",
        "fileName": "llythyr_grant_q1.pdf",
        "financialYear": "2024/25",
        "creationDate": "15 Apr 2024",
        "documentName": "Grant letter Q1",
        "isLatest": false
      }
    ]
  },
  "2023 to 2024": {
    "EN": [
      {
        "id": "jkl012opq",
        "fileName": "notice_assessment.pdf",
        "financialYear": "2023/24",
        "creationDate": "20 Mar 2024",
        "documentName": "Notice of assessment",
        "isLatest": false
      }
    ]
  },
  "currentFiscalYear": "2024/25"
}

​
Implementation Details

The endpoint performs the following operations:
  1. Validates the localAuthority parameter (required, trimmed string)
  2. Checks authorization via the access control plugin
  3. Fetches document metadata from FSS API: {fssApiUrl}/sn_gsm/laps_documents/{localAuthority}
  4. Processes the response to group documents by financial year (April 6 - April 5) and language
  5. Marks documents created within 30 days as “latest”
  6. Logs the action for audit purposes with outcome (Success/Failure)
The financial year runs from April 6 to April 5 (UK tax year). Documents are automatically categorized based on their creation date.

Build docs developers (and LLMs) love

Get started for freeTalk to us