MY PROP JOURNAL

Documents

Upload and manage trading-related documents

Overview

The Documents API allows you to upload, organize, and manage important trading documents like payout confirmations, evaluation certificates, and receipts.

Base URL: /api/v1/documents

Supported formats: JPEG, PNG, WebP, PDF
Maximum file size: 25MB

List Documents

Retrieves your uploaded documents with optional filters.

GET /api/v1/documents

Query Parameters

ParameterTypeDescription
limitintegerNumber of results (1-100, default: 20)
offsetintegerPagination offset (default: 0)
account_idstringFilter by account ID
categorystringFilter by document category
searchstringSearch document name or account number
start_datestringFilter by upload date (YYYY-MM-DD)
end_datestringFilter by upload date (YYYY-MM-DD)

Response

{
  "data": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "account_id": "uuid",
      "document_url": "https://...",
      "document_name": "January 2024 Payout",
      "category": "payout-confirmation",
      "file_name": "payout_jan_2024.pdf",
      "file_size": 524288,
      "mime_type": "application/pdf",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 8,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Get Single Document

Retrieves details for a specific document.

GET /api/v1/documents/{id}

Upload Document

Uploads a new document or replaces an existing one.

POST /api/v1/documents
Content-Type: multipart/form-data

file: <binary>
document_name: "January 2024 Payout"
category: "payout-confirmation"
account_number: "ACC-12345"
replace: false
document_id: (required if replace=true)

Form Fields

FieldRequiredDescription
fileYesThe file to upload (JPEG, PNG, WebP, or PDF)
document_nameYesDescriptive name for the document
categoryYesDocument category (see categories below)
account_numberYesAccount number this document belongs to
replaceNoSet to true to replace an existing document
document_idConditionalRequired when replace=true

Document Categories

  • payout-confirmation - Proof of payout receipt
  • evaluation-pass-certificate - Evaluation phase completion certificate
  • account-scale-certificate - Account scaling milestone certificate
  • receipt - Purchase receipts (fees, subscriptions, etc.)

Response

{
  "data": {
    "id": "uuid",
    "user_id": "uuid",
    "account_id": "uuid",
    "document_url": "https://...",
    "document_name": "January 2024 Payout",
    "category": "payout-confirmation",
    "file_name": "payout_jan_2024.pdf",
    "file_size": 524288,
    "mime_type": "application/pdf",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Update Document Metadata

Updates document name or category (does not replace the file).

PUT /api/v1/documents/{id}
Content-Type: application/json

{
  "document_name": "January 2024 Payout - Updated",
  "category": "payout-confirmation"
}

Delete Document

Deletes a document and its file from storage.

DELETE /api/v1/documents/{id}

File Removal

Deleting a document will permanently remove the file from storage. This action cannot be undone. The API response will confirm if the file was successfully removed from storage.

Replace Document File

To replace an existing document's file while keeping the same ID:

POST /api/v1/documents
Content-Type: multipart/form-data

file: <new_binary_file>
document_name: "January 2024 Payout"
category: "payout-confirmation"
account_number: "ACC-12345"
replace: true
document_id: "existing-document-uuid"

Examples

Upload Payout Confirmation

curl -X POST https://app.mypropjournal.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@payout_confirmation.pdf" \
  -F "document_name=January 2024 Payout" \
  -F "category=payout-confirmation" \
  -F "account_number=ACC-12345"

List Documents by Category

GET /api/v1/documents?category=payout-confirmation

Search Documents

GET /api/v1/documents?search=January

List Documents for Specific Account

GET /api/v1/documents?account_id=uuid

File Storage

Documents are stored securely in private storage. The document_url field contains a signed URL that expires after 1 year. To refresh the URL, fetch the document again.

Error Handling

Invalid File Type

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid file type. Allowed types: JPEG, PNG, WebP, PDF"
  }
}

File Too Large

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "File size exceeds 25MB limit"
  }
}

Account Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Account not found"
  }
}

Best Practices

  1. Use descriptive names - Include date and description in document names
  2. Organize by category - Consistent categorization makes documents easier to find
  3. PDF for important documents - Use PDF format for official certificates and confirmations
  4. Regular backups - While documents are stored securely, maintain your own backups
  5. Clean up unused documents - Delete documents you no longer need to save storage space
  6. Compress large files - Compress images before upload to stay under the 25MB limit