🏠 Overview › 🔌 API Contracts ›🔌 Approval Workflow Service

Approval Workflow Service

API Contract

REST /api/v1/claims 9 endpoints
GET /api/v1/claims/api/v1/claims

List claims across the workflow

Public

Response Example

{
  "data": [
    {
      "claim_id": "clm_9f2a3b4c",
      "user_id": "usr_84cd12ef",
      "organisation_id": "org_001",
      "status": "pending_coordinator",
      "total_amount": 4850,
      "submitted_at": "2026-03-20T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 43
  }
}
GET /api/v1/claims/api/v1/claims/:claim_id

Get full claim with current workflow status

Public

Response Example

{
  "claim_id": "clm_9f2a3b4c",
  "user_id": "usr_84cd12ef",
  "organisation_id": "org_001",
  "status": "pending_coordinator",
  "total_amount": 4850,
  "total_distance_km": 0,
  "expense_lines": [
    {
      "line_id": "line_001",
      "description": "Train Oslo-Bergen",
      "amount": 1200,
      "category": "transport"
    },
    {
      "line_id": "line_002",
      "description": "Hotel 2 nights",
      "amount": 3650,
      "category": "accommodation"
    }
  ],
  "created_at": "2026-03-20T09:15:00Z",
  "updated_at": "2026-03-21T11:30:00Z"
}
POST /api/v1/claims/api/v1/claims

Create and optionally submit a new claim

Public

Request Example

{
  "user_id": "usr_84cd12ef",
  "organisation_id": "org_001",
  "expense_lines": [
    {
      "description": "Train Oslo-Bergen",
      "amount": 1200,
      "category": "transport",
      "distance_km": 0
    },
    {
      "description": "Hotel 2 nights",
      "amount": 3650,
      "category": "accommodation",
      "distance_km": 0
    }
  ]
}

Response Example

{
  "claim_id": "clm_9f2a3b4c",
  "user_id": "usr_84cd12ef",
  "organisation_id": "org_001",
  "status": "draft",
  "total_amount": 4850,
  "created_at": "2026-03-26T08:00:00Z",
  "updated_at": "2026-03-26T08:00:00Z"
}
PUT /api/v1/claims/api/v1/claims/:claim_id

Update a draft claim before submission

Public

Request Example

{
  "expense_lines": [
    {
      "description": "Train Oslo-Bergen",
      "amount": 1200,
      "category": "transport",
      "distance_km": 0
    },
    {
      "description": "Hotel 3 nights",
      "amount": 5475,
      "category": "accommodation",
      "distance_km": 0
    }
  ]
}

Response Example

{
  "claim_id": "clm_9f2a3b4c",
  "status": "draft",
  "total_amount": 6675,
  "updated_at": "2026-03-26T09:30:00Z"
}
DELETE /api/v1/claims/api/v1/claims/:claim_id

Delete a draft claim

Public

Response Example

{
  "deleted": true,
  "claim_id": "clm_9f2a3b4c"
}
POST /api/v1/claims/api/v1/claims/:claim_id/submit

Submit a claim into the approval workflow (submitClaim)

Public

Request Example

{
  "user_id": "usr_84cd12ef"
}

Response Example

{
  "claim_id": "clm_9f2a3b4c",
  "submitted_by": "usr_84cd12ef",
  "new_status": "pending_coordinator",
  "auto_approved": false,
  "submitted_at": "2026-03-26T08:05:00Z"
}
POST /api/v1/claims/api/v1/claims/:claim_id/auto-approve

Trigger auto-approval for an eligible claim (autoApprove)

Public

Response Example

{
  "claim_id": "clm_7e8f9a0b",
  "new_status": "auto_approved",
  "approved_at": "2026-03-26T08:05:02Z",
  "reason": "Combined total 480.00 NOK is below auto-approval threshold of 1000.00 NOK"
}
POST /api/v1/claims/api/v1/claims/:claim_id/approve

Coordinator approves a pending claim (coordinatorApprove)

Public

Request Example

{
  "coordinator_id": "usr_coord99",
  "comment": "All receipts verified and amounts confirmed."
}

Response Example

{
  "claim_id": "clm_9f2a3b4c",
  "new_status": "approved",
  "coordinator_id": "usr_coord99",
  "comment": "All receipts verified and amounts confirmed.",
  "approved_at": "2026-03-21T11:30:00Z"
}
POST /api/v1/claims/api/v1/claims/:claim_id/reject

Coordinator rejects a pending claim (coordinatorReject)

Public

Request Example

{
  "coordinator_id": "usr_coord99",
  "comment": "Original hotel receipt missing. Please resubmit with documentation."
}

Response Example

{
  "claim_id": "clm_9f2a3b4c",
  "new_status": "rejected",
  "coordinator_id": "usr_coord99",
  "comment": "Original hotel receipt missing. Please resubmit with documentation.",
  "rejected_at": "2026-03-21T14:00:00Z"
}

Additional Metadata

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