ADAM

Documents

Use these endpoints to list, view, download, upload, update and delete documents stored in ADAM. A token can only reach the document categories it has permission for.

All endpoints on this page are under /api/documents/.

See Authentication for how to send your API token.

Documents/categories:get

Returns a list of document categories that the current API token has any permissions for, along with the permission flags for each.

Request

GET /api/documents/categories

Parameters

None.

Response

The data attribute will be an array of zero or more JSON objects representing categories.

Example:

GET /api/documents/categories

{
    "data": [
        {
            "category_id": 7,
            "category_name": "Photographs",
            "description": "Pupil photographs",
            "parent_id": 1,
            "permissions": {
                "read": true,
                "add": true,
                "delete": false
            }
        }
    ],
    "message": "",
    "response": {
        "error": "OK",
        "code": 200
    }
}
  • category_id is ADAM’s internal identifier for the category.
  • category_name is the display name of the category.
  • description is the category’s description text.
  • parent_id is the identifier of the parent category (top-level categories have a parent of 0).
  • permissions indicates which operations the token is allowed to perform on this category.

Documents/list:get

Returns a list of documents for a given entity within a specific category.

Request

GET /api/documents/list/<categoryId>/<entityId>

Parameters

  • categoryId: The ADAM identifier of the document category.
  • entityId: The ADAM identifier of the entity (pupil, staff member, family, or site record).

Response

The data attribute will be an array of zero or more JSON objects representing documents. Requires read permission on the category.

Example:

GET /api/documents/list/108/4561

{
    "data": [
        {
            "document_id": 12345,
            "name": "Birth Certificate",
            "filename": "birth_cert.pdf",
            "filetype": "application/pdf",
            "upload_date": "2025-03-15 10:30:00",
            "category_id": 108,
            "link": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
        }
    ],
    "message": "",
    "response": {
        "error": "OK",
        "code": 200
    }
}
  • document_id is ADAM’s internal identifier for the document.
  • name is the descriptive name given to the document.
  • filename is the original filename of the uploaded file.
  • filetype is the MIME type of the document.
  • upload_date is the date and time the document was uploaded.
  • category_id is the category the document belongs to.
  • link is a unique random string identifier for the document.

Documents/document:get

Returns detailed metadata for a single document, including its entity links.

Request

GET /api/documents/document/<documentId>

Parameters

  • documentId: The ADAM identifier of the document.

Response

The data attribute will be a JSON object with document metadata and linked entities. Requires read permission on the document’s category.

Example:

GET /api/documents/document/12345

{
    "data": {
        "document_id": 12345,
        "name": "Birth Certificate",
        "notes": "",
        "filename": "birth_cert.pdf",
        "filetype": "application/pdf",
        "upload_date": "2025-03-15 10:30:00",
        "category_id": 108,
        "category_name": "Admin Documents",
        "link": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "links": [
            {
                "table": "pupils",
                "entity_id": 4561,
                "link_date": "2025-03-15 10:30:00"
            }
        ]
    },
    "message": "",
    "response": {
        "error": "OK",
        "code": 200
    }
}
  • notes is any additional notes attached to the document.
  • category_name is the display name of the document’s category.
  • links is an array of entity associations. Each link contains the entity table (pupils, staff, families, or site), the entity_id, and the link_date.

Documents/download:get

Downloads the binary file content of a document.

Request

GET /api/documents/download/<documentId>

Parameters

  • documentId: The ADAM identifier of the document.

Response

Returns the raw binary file content with the appropriate Content-type header. Requires read permission on the document’s category.

If the document is not found, a standard JSON error response is returned with code 404.

Documents/upload:post

Uploads a new document and links it to an entity.

Request

POST /api/documents/upload

The request body must be JSON with the following fields:

Parameters

  • category (required): The ADAM identifier of the target category.
  • entity_type (required): The type of entity to link the document to. Must be one of: pupils, staff, families, site.
  • entity_id (required): The ADAM identifier of the entity.
  • name (required): A descriptive name for the document.
  • filename (required): The filename (e.g. report.pdf).
  • file_data (required): The file content encoded as a base64 string.
  • mimetype (optional): The MIME type. If omitted, ADAM will attempt to detect it automatically.

Response

Returns the new document’s identifier. Requires add permission on the target category.

Example request body:

{
  "category": 108,
  "entity_type": "pupils",
  "entity_id": 4561,
  "name": "Medical Certificate",
  "filename": "medical.pdf",
  "file_data": "JVBERi0xLjQK..."
}

Example response:

{
  "data": {
    "document_id": 12346,
    "message": "Document uploaded successfully"
  },
  "message": "",
  "response": {
    "error": "OK",
    "code": 200
  }
}

Documents/document:patch

Updates the metadata of an existing document. Can change the name, notes, or move the document to a different category.

Request

PATCH /api/documents/document/<documentId>

The request body must be JSON with one or more of the following fields:

Parameters

  • documentId (URL): The ADAM identifier of the document.
  • name (optional): New descriptive name for the document.
  • notes (optional): New notes text for the document.
  • category (optional): ADAM identifier of a category to move the document to. The token must also have add permission on the destination category.

Response

Returns a success message. Requires add permission on the document’s current category (and on the destination category if moving).

Example request body:

{
  "name": "Updated Certificate",
  "notes": "Verified by admin"
}

Example response:

{
  "data": {
    "message": "Document updated successfully"
  },
  "message": "",
  "response": {
    "error": "OK",
    "code": 200
  }
}

Documents/document:delete

Permanently deletes a document and its file from the repository.

Request

DELETE /api/documents/document/<documentId>

Parameters

  • documentId: The ADAM identifier of the document.

Response

Returns a success message. Requires delete permission on the document’s category.

Example:

DELETE /api/documents/document/12345

{
  "data": {
    "message": "Document deleted successfully"
  },
  "message": "",
  "response": {
    "error": "OK",
    "code": 200
  }
}