Mileage Claim Repository - API Contract

GET /api/v1/claims/api/v1/claims

List mileage claims. Filter by user_id, org_id, or status.

Public

Response Example

{
  "data": [
    {
      "id": "clm_01HXQR9B2T",
      "user_id": "usr_abc123",
      "org_id": "org_xyz789",
      "distance_km": 42.5,
      "rate_per_km": 0.45,
      "amount": 19.13,
      "status": "pending",
      "trip_date": "2026-03-25",
      "purpose": "Client site visit — Waterford office",
      "additional_expenses": [],
      "created_at": "2026-03-25T14:30:00Z",
      "updated_at": "2026-03-25T14:30:00Z"
    },
    {
      "id": "clm_01HXQR7A1K",
      "user_id": "usr_abc123",
      "org_id": "org_xyz789",
      "distance_km": 18,
      "rate_per_km": 0.45,
      "amount": 8.1,
      "status": "auto_approved",
      "trip_date": "2026-03-20",
      "purpose": "Training session",
      "additional_expenses": [],
      "created_at": "2026-03-20T09:10:00Z",
      "updated_at": "2026-03-20T09:10:05Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/claims/api/v1/claims/:id

Fetch a single mileage claim by ID.

Public

Response Example

{
  "id": "clm_01HXQR9B2T",
  "user_id": "usr_abc123",
  "org_id": "org_xyz789",
  "distance_km": 42.5,
  "rate_per_km": 0.45,
  "amount": 19.13,
  "status": "pending",
  "trip_date": "2026-03-25",
  "purpose": "Client site visit — Waterford office",
  "additional_expenses": [
    {
      "description": "Toll",
      "amount_eur": 2.5
    }
  ],
  "created_at": "2026-03-25T14:30:00Z",
  "updated_at": "2026-03-25T14:30:00Z"
}

POST /api/v1/claims/api/v1/claims

Create a new mileage claim record directly (used internally by mileage-claim-service after domain validation).

Public

Request Example

{
  "user_id": "usr_abc123",
  "org_id": "org_xyz789",
  "distance_km": 42.5,
  "rate_per_km": 0.45,
  "amount": 19.13,
  "status": "pending",
  "trip_date": "2026-03-25",
  "purpose": "Client site visit — Waterford office",
  "additional_expenses": [
    {
      "description": "Toll",
      "amount_eur": 2.5
    }
  ]
}

Response Example

{
  "id": "clm_01HXQR9B2T",
  "user_id": "usr_abc123",
  "org_id": "org_xyz789",
  "distance_km": 42.5,
  "rate_per_km": 0.45,
  "amount": 19.13,
  "status": "pending",
  "trip_date": "2026-03-25",
  "purpose": "Client site visit — Waterford office",
  "additional_expenses": [
    {
      "description": "Toll",
      "amount_eur": 2.5
    }
  ],
  "created_at": "2026-03-25T14:30:00Z",
  "updated_at": "2026-03-25T14:30:00Z"
}

PUT /api/v1/claims/api/v1/claims/:id

Update a claim — typically used to patch status (e.g. approved, rejected) or correct a field before approval.

Public

Request Example

{
  "status": "approved",
  "purpose": "Client site visit — Waterford office (corrected)",
  "additional_expenses": []
}

Response Example

{
  "id": "clm_01HXQR9B2T",
  "user_id": "usr_abc123",
  "org_id": "org_xyz789",
  "distance_km": 42.5,
  "rate_per_km": 0.45,
  "amount": 19.13,
  "status": "approved",
  "trip_date": "2026-03-25",
  "purpose": "Client site visit — Waterford office (corrected)",
  "additional_expenses": [],
  "created_at": "2026-03-25T14:30:00Z",
  "updated_at": "2026-03-25T15:02:11Z"
}

DELETE /api/v1/claims/api/v1/claims/:id

Soft-delete or withdraw a pending claim. Claims in approved/rejected state cannot be deleted.

Public

Response Example

{
  "id": "clm_01HXQR9B2T",
  "deleted": true,
  "deleted_at": "2026-03-25T16:00:00Z"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}