# Upload evidence (https://docs.chargeflow.io/docs/merchants/automation/upload-evidence)



The Upload Evidence API allows you to attach supporting documents directly to a dispute. Use it when you have screenshots, delivery confirmations, signed invoices, or other file-based artifacts that strengthen your chargeback response.

## When to upload evidence [#when-to-upload-evidence]

* Screenshots of customer communications (support tickets, email threads, chat logs)
* Proof of delivery or tracking confirmation documents
* Signed invoices or order confirmations
* Any additional documentation that corroborates your response narrative

<Callout type="idea" title="Tip">
  Upload evidence as early as possible after receiving a `dispute.created` event. Chargeflow
  incorporates uploaded files into the evidence package before submission, so the sooner they
  arrive, the more time the AI has to build around them.
</Callout>

## Endpoint [#endpoint]

```
POST https://api.chargeflow.io/public/2025-04-01/disputes/{disputeId}/evidence
```

This is a `multipart/form-data` request. Pass the Chargeflow dispute ID as the path parameter.

### Request fields [#request-fields]

| Field                    | Type   | Required    | Description                                                                           |
| ------------------------ | ------ | ----------- | ------------------------------------------------------------------------------------- |
| `file`                   | binary | Yes         | The file to upload                                                                    |
| `evidenceUploadCategory` | string | Yes         | Category of the evidence (see values below)                                           |
| `content`                | string | Conditional | Required when `evidenceUploadCategory` is `additional_evidence` or `additional_notes` |

**`evidenceUploadCategory` values:**

| Value                    | Description                                                                  |
| ------------------------ | ---------------------------------------------------------------------------- |
| `tracking_information`   | Shipping tracking documents or delivery confirmations                        |
| `customer_communication` | Screenshots or transcripts of customer conversations                         |
| `invoice`                | Invoices or order confirmations                                              |
| `additional_evidence`    | Any other supporting evidence (requires `content` field)                     |
| `additional_notes`       | Free-form notes to accompany the dispute response (requires `content` field) |

### Supported file types [#supported-file-types]

* Images: PNG, JPG
* Documents: PDF
* Maximum file size: 5 MB

## Example: upload a customer communication screenshot [#example-upload-a-customer-communication-screenshot]

```bash title="Terminal"
curl -X POST https://api.chargeflow.io/public/2025-04-01/disputes/DISPUTE_ID/evidence \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/screenshot.png" \
  -F "evidenceUploadCategory=customer_communication"
```

## Example: upload tracking information with a note [#example-upload-tracking-information-with-a-note]

```bash title="Terminal"
curl -X POST https://api.chargeflow.io/public/2025-04-01/disputes/DISPUTE_ID/evidence \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/delivery-confirmation.pdf" \
  -F "evidenceUploadCategory=additional_evidence" \
  -F "content=FedEx delivery confirmation showing package signed for at customer address on Jan 26."
```

## Response [#response]

A successful upload returns `200 OK` with the evidence ID:

```json title="Response"
{
  "requestId": "req_abc123def456",
  "evidenceId": "evd_789xyz"
}
```

## Upload-specific errors [#upload-specific-errors]

A file larger than 5 MB is rejected with a `400`. For the full list of HTTP status codes and the standard error response shape, see [Error handling](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling).

## Next steps [#next-steps]

<Cards>
  <Card title="Enrich a dispute" href="./enrich-a-dispute">
    Send structured data alongside file uploads.
  </Card>

  <Card title="Add customer communications" href="./enrich-a-dispute/customer-communications">
    Log structured message records (not file uploads) via the dedicated endpoint.
  </Card>

  <Card title="Enrich by business model" href="./enrich-a-dispute/by-business-model">
    The structured evidence that pairs with your uploads, for SaaS or physical goods.
  </Card>
</Cards>