Documentation

Expenses

Create and approve expense claims from your app.

Requires scope: expenses

Create requires employeeId, title, category, amount, expenseDate. Status defaults to submitted.

Approve/reject require approverId (manager, HR, org-admin, or it-admin).

Endpoints

GET/api/v1/integrations/expensesBearer auth

List expenses

Query: from, to, status, category, employeeId, page, limit, search

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "expenses": [
      {
        "id": "665f1a2b3c4d5e6f7a8b9c66",
        "employeeId": "665f1a2b3c4d5e6f7a8b9c0d",
        "title": "Client dinner",
        "category": "meals",
        "amount": 1200,
        "currency": "INR",
        "expenseDate": "2026-11-10T00:00:00.000Z",
        "status": "submitted",
        "departmentId": null,
        "projectId": null
      }
    ],
    "pagination": { "currentPage": 1, "totalPages": 1, "totalItems": 1 }
  }
}

GET/api/v1/integrations/expenses/:idBearer auth

Get one expense

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "expense": {
      "id": "665f1a2b3c4d5e6f7a8b9c66",
      "employeeId": "665f1a2b3c4d5e6f7a8b9c0d",
      "title": "Client dinner",
      "description": "Dinner with prospect",
      "category": "meals",
      "amount": 1200,
      "currency": "INR",
      "expenseDate": "2026-11-10T00:00:00.000Z",
      "status": "submitted"
    }
  }
}

POST/api/v1/integrations/expensesBearer auth

Create an expense claim

Request body

{
  "employeeId": "<employeeId>",
  "title": "Client dinner",
  "category": "meals",
  "amount": 1200,
  "currency": "INR",
  "expenseDate": "2026-11-10",
  "description": "Dinner with prospect"
}

Example response

{
  "success": true,
  "status": 201,
  "message": "Expense created",
  "data": {
    "expense": {
      "id": "665f1a2b3c4d5e6f7a8b9c66",
      "employeeId": "665f1a2b3c4d5e6f7a8b9c0d",
      "title": "Client dinner",
      "category": "meals",
      "amount": 1200,
      "currency": "INR",
      "expenseDate": "2026-11-10T00:00:00.000Z",
      "status": "submitted"
    }
  }
}

POST/api/v1/integrations/expenses/:id/approveBearer auth

Approve an expense

Request body

{
  "approverId": "<managerOrHrUserId>",
  "notes": "Looks good"
}

Example response

{
  "success": true,
  "status": 200,
  "message": "Expense approved",
  "data": {
    "expense": {
      "id": "665f1a2b3c4d5e6f7a8b9c66",
      "title": "Client dinner",
      "amount": 1200,
      "status": "approved"
    }
  }
}

POST/api/v1/integrations/expenses/:id/rejectBearer auth

Reject an expense

Request body

{
  "approverId": "<managerOrHrUserId>",
  "reason": "Missing receipt"
}

Example response

{
  "success": true,
  "status": 200,
  "message": "Expense rejected",
  "data": {
    "expense": {
      "id": "665f1a2b3c4d5e6f7a8b9c66",
      "title": "Client dinner",
      "amount": 1200,
      "status": "rejected",
      "rejectionReason": "Missing receipt"
    }
  }
}