---
title: "Submit claims via SFTP batch"
method: POST
path: "/api/v1/claims/sftp/submit"
tags: ["Open API", "Claims SFTP Input Method"]
---

# Submit claims via SFTP batch

`POST /api/v1/claims/sftp/submit`

## Request

- Base URL: `https://developer.claimmind.life` (the document declares no server; this is the origin it was published from)
- URL: `https://developer.claimmind.life/api/v1/claims/sftp/submit`
- Auth: none declared. Required headers: `X-API-Key`

Trigger batch processing of claims uploaded via SFTP.

    **Use Case:** High-volume processing (100+ claims) or legacy systems without HTTP multipart capability.

    **Authentication:** API Key (X-API-Key header)
    **Required Scope:** `claims:write`

    **Integration Pattern:**
    1. Upload claim files to configured SFTP folder
    2. Call this endpoint to trigger batch processing
    3. Receive session_id for tracking
    4. Poll /status/{session_id} for progress
    5. Retrieve results from /result/{session_id} when complete

    **Request Format:**
    No request body required - automatically scans SFTP inbox folder based on tenant configuration.

    **Response Format:**
    - session_id: Unique batch session identifier for tracking
    - batch_total: Total number of batches to process
    - current_batch: Current batch being processed
    - sep_in_batch: Number of claims in current batch
    - status: PENDING | PROCESSING | COMPLETED | FAILED
    - temporal_workflow_id: Internal workflow identifier

    **Webhook Events:**
    - batch.started: When batch processing begins
    - batch.completed: When all claims in batch finish processing
    - batch.failed: If batch processing encounters errors

    **Cancellation:**
    - Use Temporal **Cancel** (SDK `WorkflowHandle.cancel()` or the UI "Cancel" button) to stop a batch.
      Finished claims stay in `success_claim_details`; unfinished claims are marked failed at their
      latest step (`failed_at`, `retryable=true`, `reason="cancelled_at_<step>"`, e.g.
      `cancelled_at_medical_grouper`) and appear in `failed_claim_details`.
      The DB is updated, `batch.failed` fires, and the next batch still runs.
    - **Terminate** is not supported for clean compensation — it skips all cleanup and leaves claims stuck.

    **Error Handling:**
    - 400: Invalid SFTP configuration or no files found
    - 401: Invalid API key
    - 403: API key lacks claims:write scope
    - 500: Server error - check SFTP connection

    **Example Response:**
    ```json
    {
        "session_id": "sftp-session-20260122-001",
        "batch_total": 3,
        "current_batch": 1,
        "sep_in_batch": 10,
        "status": "PENDING",
        "finished": False,
        "claim_list": [
            {"claim_id": "CLM-001", "files": ["claim.pdf"]},
            {"claim_id": "CLM-002", "files": ["claim.pdf", "lab.pdf"]}
        ],
        "temporal_workflow_id": "wf-temporal-batch-123"
    }
    ```

    **Integration Tips:**
    - Configure SFTP settings via Admin API before first use
    - Batch size configurable (default 10 claims per batch)
    - Use webhooks instead of polling for better performance
    - Upload files during off-peak hours for optimal processing

## Headers

- `X-API-Key` string, required

## Response `202`

Batch processing initiated

- unknown

## Other responses

- `400`: Bad request - SFTP not configured or no files found
- `403`: Insufficient permissions
- `422`: Validation Error

---

[API](https://skmtc.dev/claimmind/apis/claimmind-open-api-service.md) - [All operations](https://skmtc.dev/claimmind/apis/claimmind-open-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/claimmind/apis/claimmind-open-api-service/revisions/ee8bfbeadb8a?raw)