Retrieve documentation templates

This guide explains how to retrieve documentation templates and their detailed structure using the public API.

Prerequisites

• A valid set of API credentials
• A valid access token
• A valid organization code
• The scope permission stonal.document.template.read

Overview

The documentation templates API provides two main endpoints:

1. List templates - Get all available documentation templates for an organization
2. Get template details - Retrieve the complete folder tree structure for a specific template

---

List documentation templates

Step 1: Call the API

See: API Specification

GET /document-storage/v1/organizations/{organizationCode}/templates

Parameters

Name	Type	Required	Description
organizationCode	string	true	Organization code (path parameter)
language	string	false	Preferred language (query parameter, e.g., "fr-FR")

Example request

curl -X GET "https://api.stonal.io/document-storage/v1/organizations/STONAL/templates?language=fr-FR" \
-H "Authorization: Bearer {token}"

Response

{
  "templates": [
    {
      "id": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d",
      "name": "DOE Template",
      "organizationCode": "STONAL",
      "attachmentType": "BUILDING_GROUP"
    }
  ]
}

Possible responses

• 200: Successfully retrieved templates list
• 403: Forbidden (insufficient permissions)

---

Get documentation template details

Step 1: Identify the template

You must provide the templateId which is the unique identifier of the template you want to retrieve details for.

The template ID format is typically a UUID: f90ee77d-b6cc-41fa-8d1f-bea649e6d93d

note

Ensure the user has the necessary access rights to the organization and template to successfully retrieve the template details.

Step 2: Call the API

See: API Specification

GET /document-storage/v1/organizations/{organizationCode}/templates/{templateId}

Parameters

Name	Type	Required	Description
organizationCode	string	true	Organization code (path parameter)
templateId	string	true	Template unique identifier (path parameter)
language	string	false	Preferred language (query parameter, e.g., "fr-FR")

Example request

curl -X GET "https://api.stonal.io/document-storage/v1/organizations/STONAL/templates/f90ee77d-b6cc-41fa-8d1f-bea649e6d93d?language=fr-FR" \
-H "Authorization: Bearer {token}"

Response

{
  "template": {
    "id": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d",
    "name": {
      "fr-FR": "Modèle DOE"
    },
    "organizationCode": "STONAL",
    "attachmentType": "BUILDING_GROUP",
    "folders": [
      {
        "id": "folder-123",
        "name": {
          "fr-FR": "Documentation technique"
        },
        "parentId": null,
        "documentClass": {
          "identifier": "documentClassIdentifier",
          "code": "DPE"
        }
      }
    ]
  }
}

Possible responses

• 200: Successfully retrieved template details
• 404: Template not found
• 403: Forbidden (insufficient permissions)

Notes

• Language parameter: When provided, the API returns localized names in the specified language. If not provided or invalid, defaults to the system default language.
• Folder hierarchy: The folders array contains all folders with their parent-child relationships defined by the parentId field.
• Root folders: Folders with parentId: null are root-level folders.
• Document classes: Some folders may have associated document classes that define the type of documents that can be stored.

Error Handling

Common error scenarios:

• Missing or expired access token → 401 Unauthorized
• Insufficient scope permissions → 403 Forbidden
• Invalid organization code → 403 Forbidden
• Template not found or no access → 404 Not Found

Best practices:

• Always verify the response status code before processing the response
• Handle error responses gracefully in your implementation
• Cache template lists when appropriate to reduce API calls
• Use the language parameter to provide localized user experiences

Performance

The template details endpoint is optimized to avoid construction-then-flattening patterns for better performance when retrieving large folder structures.

Security

Both endpoints require:

• Valid authentication token
• The stonal.document.template.read scope permission
• Appropriate access rights to the organization and templates

The API automatically filters results based on the user's permissions, ensuring users only see templates they have access to.