Description

Overview

The Uploads API provides functionality for managing file uploads and documents:

• File upload and storage
• Document type management
• File validation
• Signature tracking
• Approval workflow
• Avatar management
• Customer document management

Core Concepts

Document Types

Document type codes are config-driven (uploads.documents in uploads.yaml). They are not a fixed API enum; invalid codes return 400 with uploads.invalid_document_type and an allowed_types parameter.

Common codes (deployment may add or omit keys):

Approval and signature status values are also defined under uploads.approval_status and uploads.signature_status in the same config file.

File Validation

• Supported formats: PDF, JPEG, PNG, JPG
• Size limits: 512 bytes (min) to 20MB (max)
• Content type validation
• File extension validation

Document Status

Approval Status

• pending: Awaiting approval
• approved: Document approved
• attached: No approval needed

Signature Status

• pending: Awaiting signatures
• signed: Document signed
• not_required: No signature needed

Avatar Types

• customer: Customer avatars
• user: User avatars

Endpoints

File Management

Create File

POST /v1/uploads

Upload a new file.

Request Body:

{
  "file_name": "customer_agreement.pdf",
  "content": "base64_encoded_content",
  "document_type": "customer_agreement",
  "approval_needed": 1,
  "approval_made": 0,
  "signature_needed": 1,
  "signature_made": 0,
  "active": true,
  "metadata": {
    "department": "legal",
    "priority": "high"
  }
}

Response:

{
  "id": "uuid",
  "file_name": "customer_agreement.pdf",
  "document_type": "customer_agreement",
  "approval_status": "pending",
  "approval_needed": 1,
  "approval_made": 0,
  "signature_status": "pending",
  "signature_needed": 1,
  "signature_made": 0,
  "content_length": 15360,
  "file_extension": "application/pdf",
  "active": true,
  "metadata": {
    "department": "legal",
    "priority": "high",
    "document_type_localized": "Customer Agreement",
    "approval_status_localized": "Pending Approval",
    "signature_status_localized": "Pending Signature"
  },
  "created_at": "2024-03-21T10:00:00Z",
  "created_by": "uuid"
}

Get All Files

GET /v1/uploads

List all files with optional filtering.

Query Parameters:

• isSigned: Filter signed documents
• isApproved: Filter approved documents

Get File

GET /v1/uploads/{id}

Get file metadata.

Get File Content

GET /v1/uploads/{id}/content

Get file content.

Response:

{
  "file_name": "customer_agreement.pdf",
  "content": "base64_encoded_content",
  "file_extension": "application/pdf",
  "document_type": "customer_agreement"
}

Update File

PUT /v1/uploads/{id}

Replace upload metadata (file_name, approval/signature counts, active, metadata). To change document_type, use PATCH below.

Request Body:

{
  "file_name": "updated_customer_agreement.pdf",
  "approval_needed": 2,
  "signature_needed": 2,
  "metadata": {
    "department": "legal",
    "status": "revised"
  },
  "active": true
}

Patch File Metadata

PATCH /v1/uploads/{id}

Change upload metadata partially. Use this to reclassify a document (document_type) without a full PUT body.

Request Body:

{
  "document_type": "bylaws"
}

document_type must be a valid code from uploads.documents in app config. The response includes updated document_type_localized and catalog icon in metadata.

Upload change history

GET /v1/uploads/{id}/history

Returns blame audit rows for one upload (create, update, delete, type change, signature adjustments). Requires read permission on the upload.

Customer upload history counts

GET /v1/uploads/customer/{customer_id}/history-counts

Returns { "counts": { "": , ... } } for uploads linked to the customer that the caller may read. Used by Configurator to show history icons without calling Internal-only /v1/blame/count.

Delete File

DELETE /v1/uploads/{id}

Delete a file.

Adjust Signature Count

PATCH /v1/uploads/{id}/signature

Increment or decrement the signature count (adjust_by). This is separate from PATCH /v1/uploads/{id}, which updates metadata such as document_type.

Request Body:

{
  "adjust_by": 1
}

Customer Document Management

Create Customer File

POST /v1/uploads/customer/{customer_id}

Upload a file for a specific customer. Requires update permission on the customers record identified by customer_id, plus create permission on uploads. The upload is linked to that customer; customer_id in the URL is authoritative (body cannot target another customer).

Get Customer Files

GET /v1/uploads/customer/{customer_id}

Get all files for a customer. Requires read permission on the customer, then returns only uploads linked to that customer that the caller may read.

Query Parameters:

• isSigned: Filter signed documents
• isApproved: Filter approved documents
• tag: Filter by document tag

Get Customer File By Type

GET /v1/uploads/customer/{customer_id}/file/type/{file_type}

Get customer files of a specific type.

Error Codes

Message keys are defined in (and related packages). API error responses use the wire code string (first column below), not Go constant names.

Upload module (uploads.*)

Related codes (other modules, used by uploads)