Skip to main content
POST
/
documents
/
upload
Upload Document
curl --request POST \
  --url http://api.gu1.ai/documents/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityId": "<string>",
  "categoryId": "<string>"
}
'
{
  "400": {},
  "401": {},
  "500": {},
  "id": "<string>",
  "name": "<string>",
  "originalFileName": "<string>",
  "fileSize": 123,
  "mimeType": "<string>",
  "storagePath": "<string>",
  "storageProvider": "<string>",
  "categoryId": "<string>",
  "organizationId": "<string>",
  "createdAt": {}
}
Upload files associated with entities using multipart/form-data.

​
Authentication

This endpoint requires authentication via Bearer token and organization context. Required Headers:
  • Authorization: Bearer <jwt-token>
  • X-Organization-ID: <organization-id>

​
Form Data Parameters

​
file
File
required
The file to upload (any type supported)
​
entityId
UUID
ID of the entity to associate the document with
​
categoryId
UUID
ID of the document category (UBO, Legal Representative, Corporate, etc.)

​
Request Example

curl -X POST https://api.gu1.ai/documents/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID" \
  -F "file=@/path/to/document.pdf" \
  -F "entityId=bb0c2d24-b519-40ec-b765-86de831ca0af" \
  -F "categoryId=c5e9a3f2-1234-5678-9abc-def012345678"

​
Response

​
id
UUID
Unique identifier for the document
​
name
string
Display name of the document
​
originalFileName
string
Original filename of the uploaded file
​
fileSize
number
File size in bytes
​
mimeType
string
MIME type of the file
​
storagePath
string
Path where the file is stored (S3 key or local path)
​
storageProvider
string
Storage provider used (‘s3’ or ‘local’)
​
categoryId
UUID
ID of the document category (if assigned)
​
organizationId
UUID
ID of the organization that owns the document
​
createdAt
timestamp
When the document was created

​
Response Example

{
  "id": "d7f8e9c0-1234-5678-9abc-def012345678",
  "name": "document.pdf",
  "description": "Documento subido: document.pdf",
  "type": "other",
  "fileName": "1730649606123_document.pdf",
  "originalFileName": "document.pdf",
  "fileSize": 245678,
  "mimeType": "application/pdf",
  "fileExtension": "pdf",
  "storagePath": "/uploads/1730649606123_document.pdf",
  "storageProvider": "local",
  "securityLevel": "internal",
  "categoryId": "c5e9a3f2-1234-5678-9abc-def012345678",
  "organizationId": "24236b0a-e34d-4218-b3d2-76b101ce8aa9",
  "createdBy": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "createdAt": "2025-11-03T15:30:45.123Z",
  "updatedAt": "2025-11-03T15:30:45.123Z"
}

​
What Happens After Upload

  1. Storage: File is uploaded to S3 (if enabled) or local storage
  2. Database Record: Document record is created in the database
  3. Versioning: Initial version (v1) is automatically created
  4. Entity Relationship: If entityId is provided, a relationship is created automatically
  5. Risk Analysis: Automatic risk analysis is triggered if rules are configured

​
Supported File Types

  • Documents: PDF, DOC, DOCX, TXT
  • Images: PNG, JPG, JPEG, GIF
  • Spreadsheets: XLS, XLSX, CSV
  • Others: Any file type

​
Document Categories

To get available categories, use: 
GET /documents/categories
Common categories include:
  • UBO (Ultimate Beneficial Owner)
  • Legal Representative
  • Corporate Documents
  • Enhanced Due Diligence

​
Error Responses

​
400
error
Bad Request - Missing file or authentication
{
  "error": "No file provided"
}
​
401
error
Unauthorized - Invalid token
{
  "error": "Unauthorized - No token provided"
}
​
500
error
Internal Server Error
{
  "error": "Error interno del servidor",
  "details": "Error message here"
}

​
Notes

The system automatically detects if S3 storage is configured and uses it, otherwise falls back to local storage.
Maximum file size depends on server configuration (typically 50MB).
Even if entityId or categoryId don’t exist, the document will still be created. The relationship or category assignment will simply be skipped.