Skip to main content

​
Files

Files are PDF documents uploaded to DokStamp before being attached to certificates or documents. Each file can only be used by one certificate — once attached, it is marked as used and cannot be reused.

​
The file object

{
  "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
  "original_name": "diploma-maria-silva.pdf",
  "mime_type": "application/pdf",
  "extension": "pdf",
  "size": 245760,
  "used_at": null,
  "file": "https://storage.dokstamp.eu/files/h8i9j0k1.pdf"
}
FieldTypeDescription
uuidstringUnique identifier — use as file_uuid when creating certificates
original_namestringOriginal filename
mime_typestringMIME type (e.g., application/pdf)
extensionstringFile extension
sizeintegerFile size in bytes
used_atdatetime|nullNull = available. Non-null = already attached to a certificate.
filestringDirect download URL

​
Upload files

POST /files
Accepts multipart/form-data. You can upload multiple files in a single request.
ParameterTypeRequiredDescription
files[]fileYesOne or more PDF files
# Upload a single file
curl -X POST https://api.dokstamp.com/files \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "X-Tenant: {TENANT}" \
  -F "files[]=@/path/to/diploma-maria-silva.pdf"

# Upload multiple files at once
curl -X POST https://api.dokstamp.com/files \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "X-Tenant: {TENANT}" \
  -F "files[]=@diploma-1.pdf" \
  -F "files[]=@diploma-2.pdf" \
  -F "files[]=@diploma-3.pdf"
Response 201: 
{
  "data": [
    {
      "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
      "original_name": "diploma-maria-silva.pdf",
      "mime_type": "application/pdf",
      "size": 245760,
      "used_at": null
    }
  ]
}

​
List files

GET /files
Filter for unused files (available to attach to new certificates): 
GET /files?where[used_at]=null

​
Get file metadata

GET /files/{uuid}

​
Download a file

GET /files/{uuid}/download
This endpoint is public — no Authorization header required. Share this URL directly with signers, students, or employers.
curl "https://api.dokstamp.com/files/h8i9j0k1-l2m3-4567-nopq-678901234567/download" \
  --output diploma.pdf

​
Update file metadata

PATCH /files/{uuid}
PUT   /files/{uuid}

​
Delete a file

DELETE /files/{uuid}
You cannot delete a file that is already attached to a certificate (used_at is not null). Delete or revoke the certificate first.

​
Deduplication

The API computes a hash for each uploaded file. If you upload the same file content twice, the second upload returns the existing file record instead of creating a duplicate. This prevents storage bloat in batch upload workflows.