---
title: "Upload evidence files"
method: POST
path: "/dispute/disputes/{disputeId}/evidences"
tags: ["Disputes"]
---

# Upload evidence files

`POST /dispute/disputes/{disputeId}/evidences`

## Request

- Base URL: `https://api.staging.payrails.io`
- URL: `https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/payrails/apis/payrails-api-reference/docs/dispute/disputes/:disputeId/evidences/post.ts> (a function with typed inputs; its response is checked against the schema)

Upload evidence files on the dispute.

## Path parameters

- `disputeId` string, uuid, required

## Headers

- `x-idempotency-key` string, uuid, required

## Request body `multipart/form-data`

- object: Evidence to upload for the dispute. Provide at least one of `files[]` (binary file uploads) or `inlineContexts` (inline JSON context); both may be combined in a single request. A request with neither is rejected.
  - `files[]` object[]: List of files supporting the dispute defense.
  - `inlineContexts` object[]: Inline merchant-context evidences supplied as a JSON array in a single `inlineContexts` form field. Each item is stored as JSON evidence with no uploaded file. Maximum 10 items.
    - `title` string: Optional display title for the inline context. When omitted or blank it defaults to "inline-context".
    - `payload` object, required: Arbitrary JSON object stored verbatim as the evidence payload. Maximum 64 KB.

## Response `201`

Dispute evidences uploaded.

- object
  - `evidences` object[], required
    - `id` string, uuid, required: Unique identifier of the Dispute in Payrails.
    - `createdAt` string, date-time, required: Date and time when the Dispute was created in Payrails.
    - `updatedAt` string, date-time, required: Date and time when the Dispute was last updated in Payrails.
    - `displayTitle` string: Display title of the evidence, usually the file name.
    - `status` 'Active' | 'Inactive' | 'Unknown': Status of the dispute evidence.
    - `provenance` 'Merchant' | 'Payrails' | 'Unknown': Provenance of the dispute evidence.
    - `contentType` string: MIME type of the evidence content.
    - `contentLength` integer: Size of the evidence content in bytes.
    - `payload` object: Inline JSON payload for inline-context evidences. Present only for evidences created from `inlineContexts`; omitted for file-backed evidence.
    - `workspaceId` string, uuid: Workspace ID that the Dispute belongs to.
    - `labels` string[]: Labels assigned to this evidence for the dispute, used to categorise the document during representment.
  - `failedEvidences` object[], required
    - `name` string, required: Name of the evidence file.
    - `errorMessage` string, required: Error due to which evidence uploading failed.
  - `classifications` object[]: AI classifications for the uploaded evidence files. Present for each file where classification completed (status "classified" or "failed"). Omitted when the evidence agent feature is not enabled.
    - `evidenceId` string, uuid, required: Unique identifier of the evidence file that was classified.
    - `disputeId` string, uuid, required: Unique identifier of the dispute the evidence belongs to.
    - `status` 'classifying' | 'classified' | 'failed', required: Classification status.
    - `contentSummary` string: AI-generated summary of the evidence file content.
    - `documentType` string: AI-inferred document type (e.g. "receipt", "shipping_label").
    - `provesStatement` string: AI-generated statement of what the evidence proves in the dispute context.
    - `keyFacts` string[]: List of key facts extracted from the evidence.
    - `suggestedPlanMatches` object[]: Representment plan slots this evidence is suggested to fill, ordered by confidence.
      - `defenseReasonCode` string, required: Defense reason code of the plan slot this evidence matches.
      - `slug` string, required: Slug identifier of the matching plan evidence slot.
      - `position` integer, required: Position of the matching slot within the defense type.
      - `rationale` string, required: AI-generated explanation for why this evidence matches the slot.
    - `providerResponseId` string: Identifier of the LLM provider response that produced this classification.
    - `createdAt` string, date-time: Date and time when the classification was created.
    - `updatedAt` string, date-time: Date and time when the classification was last updated.

## Other responses

- `400`: Bad Request.
- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: Not Found.
- `429`: Too Many Requests.
- `500`: Internal Server Error.

---

[API](https://skmtc.dev/payrails/apis/payrails-api-reference.md) - [All operations](https://skmtc.dev/payrails/apis/payrails-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/payrails/apis/payrails-api-reference/revisions/9dd2f0158582?raw)