Skip to main content

Expenses API

Endpoints for tracking and managing expenses, including receipt uploads optimized for mobile apps.

List User Expenses​

Retrieves the current user's expense requests (up to 100 most recent). Results include category, payment method, and currency details.

GET /expenses

Response: 200 OK

{
  "status": "SUCCESS",
  "data": [
    {
      "id": 12,
      "expense_date": "2026-04-06",
      "category": 1,
      "category_Name": "Travel",
      "payment_method": 1,
      "payment_method_Name": "Credit Card",
      "currency": 1,
      "currency_Name": "USD",
      "payee": "Office Supplies Inc",
      "amount": 125.50,
      "status": "Pending"
    }
  ]
}

Add Expense​

Creates a new expense request, optionally with a receipt image.

POST /expense

Required Fields:

  • category: Expense category ID (from /expense/categories)
  • payment_method: Payment method ID (from /expense/payment-methods)
  • payee: Vendor/payee name

Request Body (with receipt):

{
  "expense_date": "2026-04-06",
  "category": 1,
  "payment_method": 1,
  "payee": "Office Supplies Inc",
  "amount": 125.50,
  "currency": 1,
  "notes": "Office supplies for Q2",
  "receipt": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

Request Body (without receipt):

{
  "expense_date": "2026-04-06",
  "category": 1,
  "payment_method": 1,
  "payee": "Taxi Service",
  "amount": 35.00,
  "notes": "Client meeting transportation"
}

Response: 201 Created

Error Response: 400 Bad Request for invalid request data or image format.

Receipt Upload (Mobile-Friendly)​

Mobile apps (Flutter, React Native, etc.) can upload camera-captured receipts directly in the JSON payload using base64 encoding. No separate file upload step is needed.

Receipt Field Options:

  • receipt: Primary receipt (base64-encoded)
  • receipt2: Optional second receipt
  • receipt3: Optional third receipt
  • receipt_filename, receipt2_filename, receipt3_filename: Optional original filenames

Base64 Format:

  • With data URI prefix: "data:image/jpeg;base64,/9j/4AAQ..."
  • Raw base64: "/9j/4AAQSkZJRg..."

Image Constraints:

  • Supported formats: jpg, jpeg, png, gif, bmp, webp, heic, heif
  • Maximum file size: 10MB per image
  • Maximum attachments: 3 receipts per expense

List Expense Categories​

Returns all available expense categories. Use the returned id when submitting an expense.

GET /expense/categories

Response: 200 OK

{
  "status": "SUCCESS",
  "data": [
    {"id": 1, "name": "Travel", "pre_approve": "Yes"},
    {"id": 2, "name": "Meals", "pre_approve": "No"}
  ]
}

List Payment Methods​

Returns all available payment methods.

GET /expense/payment-methods

Response: 200 OK

{
  "status": "SUCCESS",
  "data": [
    {"id": 1, "name": "Credit Card"},
    {"id": 2, "name": "Cash"}
  ]
}

Upload Expense Attachment (Multipart)​

Alternative to base64 encoding. Uploads a file using multipart/form-data and returns a saved filename to use in attachment1, attachment2, or attachment3 when creating an expense.

POST /expenses/file-upload

Request: multipart/form-data with a file field (max 10MB).

Response: 201 Created

{
  "status": "SUCCESS",
  "data": "17123456789012345"
}
tip

For mobile apps, prefer the base64 receipt field on POST /expense for a simpler single-request workflow.

Expense Status Values​

  • Pending: Awaiting approval
  • Approved: Approved for reimbursement
  • Rejected: Rejected by approver
  • Cancelled: Cancelled by submitter
  • Processing: Reimbursement being processed
  • Cancellation Requested: Cancellation requested after approval