--- title: Evidence API slug: evidence-api docTags: createdAt: 2026-06-01T13:20:13.044Z --- Save time and effort by using our [Evidence API endpoint](https://docs.forter.com/reference/evidence) to automatically send post-order evidence for chargeback disputes. You also have the flexibility to manually upload evidence via the Forter Portal. ## Integration Steps ::::WorkflowBlock :::WorkflowBlockItem **Create a dedicated folder for evidence files in S3** Create a dedicated folder called `dispute-evidence` in the [AWS S3 folder assigned to your site](https://portal.forter.com/app/integration/credentials/), which you will use to securely transfer all of your chargeback evidence. ::: :::WorkflowBlockItem **Upload evidence files to S3** Upload file-based evidence securely to the `dispute-evidence` folder in S3. For details on types and formats, refer to [Evidence Glossary](https://docs.forter.com/evidence-glossary). Use descriptive file names and avoid spaces when possible (use hyphens or underscores). ::: :::WorkflowBlockItem **Send request to Evidence API** If the evidence is contained within a file uploaded to S3, follow up with a request to `/v3/disputes/evidence/file` [(reference)](https://docs.forter.com/reference/evidence-file-upload) that includes the path to the file and supporting details in order to match the file to the correct dispute. If the evidence is in the form of structured data rather than a file upload, send this in a request to `/v3/disputes/evidence/datapoints` [(reference)](https://docs.forter.com/reference/evidence). Both methods can be used independently or combined based on your evidence requirements. Forter will match evidence to claims that are in first cycle and open. Evidence for claims in other statuses (e.g., expired, won, lost, etc.) will not be matched nor added to the claim. ::: :::WorkflowBlockItem **Receive response** Forter will return a response of success or failure. A successful response will include the `evidenceId` of the created document. A failure response will include error messages. For data points submissions, invalid data points will be returned in the `invalidEvidenceDatapoints` field. ::: :::: ## Key API Fields To add evidence to the appropriate representment, each evidence needs to be associated to its corresponding claim. The evidence may be associated to one or more chargeback disputes, based on the identifiers provided. Forter requires at least one of the identifiers to match the evidence to the claim. The identifiers must meet the following conditions: | **Field Name** | **Description** | **Format** | **Example** | | --------------------- | ----------------------------------------------------------------------- | ---------- | ---------------------- | | `processorCaseNumber` | The Processor Case ID that the payment processor assigns to each claim. | String | CB-43433343219 | | `processorChargeId` | The unique identifier associated with the processor charge. | String | 0073000000000096401767 | | `orderId` | The id of of the order that the evidence is linked to. | String | O6996685178152213554 | **Note** If you are planning on using `orderID` and your orders can result in more than one charge (e.g., multiple charges for multiple shipments under one order, or multiple airfare charges under one reservation), Forter may append multiple evidence files to a claim. ## API Endpoints The Evidence API provides two endpoints for different evidence submission methods: `POST /v3/disputes/evidence/file` - Evidence upload endpoint for file-based evidence `POST /v3/disputes/evidence/datapoints` - Submit structured evidence data ## File Format Requirements Supported file formats: - **PDF** - Preferred format for documents - **JPEG/JPG** - Image evidence - **PNG** - Image evidence with transparency support ## Integration Tests :::ExpandableHeading ### File Validations | **Integration Test** | **Request** | **Response** | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | File size is too large (triggered for attachments over 1MB in size) | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"PROOF_OF_DELIVERY", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/large-file-exceeds-limit.pdf" }` | `{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }` | | The evidence file format is not supported | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"CONTRACT_PAGE", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/etechTest123.txt" }` | `{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }` | | Number of evidence of the same type per claim is above the threshold | `{ "orderId":"ORD-12345678", "processorCaseNumber":"CB-87654321", "evidenceType":"CONTRACT_PAGE", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/cp1.pdf" }` | `{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }` | | Wrong evidence prefix location | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"PROOF_OF_DELIVERY", "filePath":"s3://out-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/example-16451.pdf" }` | `{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }` | | File does not exist | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"CONTRACT_PAGE", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/does-not-exist.pdf" }` | `{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }` | | File does not conform to naming requirements | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"INVOICE", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/invalid@file@name" }` | `{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }` | ::: :::ExpandableHeading ### Data Points Validations | **Integration Test** | **Request** | **Response** | | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Invalid data point structure | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "proofsOfRefund":[ { "invalidField":"invalid-value" } ] }` | `{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"proofsOfRefund[0].invalidField", "failureReason":"Field is not supported for this data point type" } ] }` | | Missing required data point fields | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "proofsOfDelivery":[ { "date":"2024-01-15" } ] }` | `{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"proofsOfDelivery[0].trackingNumber", "failureReason":"Required field is missing" } ] }` | | Data points exceed maximum array size | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "airlineTicketNumbers":["TKT001","TKT002",...,"TKT051"] }` | `{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"airlineTicketNumbers", "failureReason":"Array size exceeds maximum allowed limit of 50 items" } ] }` | | Data points exceed maximum array size (FedEx-only `fedexAccountNumber` field) | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "fedexAccountNumber":["ACCT001","ACCT002",...,"ACCT051"] }` | `{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"fedexAccountNumber", "failureReason":"Array size exceeds maximum allowed limit of 50 items" } ] }` | | Data points exceed maximum array size (`other` field) | `{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "other":["note 1","note 2",...,"note 1001"] }` | `{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"other", "failureReason":"Array size exceeds maximum allowed limit of 1000 items" } ] }` | ::: :::CodeblockTabs File evidence example ```curl curl --location --request POST 'https://{forterBaseUrl}:8443/v3/disputes/evidence/file' \ --header 'api-version: 2.1' \ --header 'x-forter-siteid: forterSiteId' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic abc123' \ --data-raw '{ "processorCaseNumber" : "CB-43433343219", "processorChargeId" : "0073000000000096401767", "orderId" : "O6996685178152213554", "evidenceType": "CONTRACT_PAGE", "filePath": "s3://forter-file-transfer//dispute-evidence/example-16451.pdf" }' ``` ::: :::CodeblockTabs Data points evidence example ```curl curl --location --request POST 'https://{forterBaseUrl}:8443/v3/disputes/evidence/datapoints' \ --header 'api-version: 2.1' \ --header 'x-forter-siteid: forterSiteId' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic abc123' \ --data-raw '{ "processorCaseNumber" : "CB-43433343219", "processorChargeId" : "0073000000000096401767", "orderId" : "O6996685178152213554", "proofsOfRefund": [ { "refundTransactionId": "REF-12345", "refundAmount": 99.99, "refundCurrency": "USD", "refundDate": "2024-01-15", "refundAuthorizationCode": "B44233", "refundChargeId": "111111111" } ], "proofsOfDelivery": [ { "trackingNumber": "1Z123456789", "carrier": "UPS", "date": "2024-01-20" } ], "airlineTicketNumbers": ["1234567890123", "1234567890124"] }' ``` ::: :::CodeblockTabs POST File Evidence example ```nodejs var axios = require('axios'); var data = JSON.stringify({ "evidenceType": "CONTRACT_PAGE", "filePath": "s3://forter-file-transfer//dispute-evidence/example-16451.pdf", "processorCaseNumber": "CB-43433343219", "processorChargeId": "0073000000000096401767", "orderId": "O6996685178152213554" }); var config = { method: 'post', url: 'https://{forterBaseUrl}/v3/disputes/evidence/file', headers: { 'api-version': '2.1', 'x-forter-siteid': 'forterSiteId', 'Content-Type': 'application/json', 'Authorization': 'Basic abc123' }, data : data }; axios(config) .then(function (response) { console.log(JSON.stringify(response.data)); }) .catch(function (error) { console.log(error); }); ``` ::: :::CodeblockTabs POST Data points evidence example ```nodejs var axios = require('axios'); var data = JSON.stringify({ "processorCaseNumber": "CB-43433343219", "processorChargeId": "0073000000000096401767", "orderId": "O6996685178152213554", "proofsOfRefund": [ { "refundTransactionId": "REF-12345", "refundAmount": 99.99, "refundCurrency": "USD", "refundDate": "2024-01-15", "refundAuthorizationCode": "B44233", "refundChargeId": "111111111" } ], "proofsOfDelivery": [ { "trackingNumber": "1Z123456789", "carrier": "UPS", "date": "2024-01-20" } ], "airlineTicketNumbers": ["1234567890123", "1234567890124"] }); var config = { method: 'post', url: 'https://{forterBaseUrl}/v3/disputes/evidence/datapoints', headers: { 'api-version': '2.1', 'x-forter-siteid': 'forterSiteId', 'Content-Type': 'application/json', 'Authorization': 'Basic abc123' }, data : data }; axios(config) .then(function (response) { console.log(JSON.stringify(response.data)); }) .catch(function (error) { console.log(error); }); ``` ::: :::CodeblockTabs Files Success response example ```json { "status": "SUCCESS", "message": "EVIDENCE_UPLOADED" } ``` ::: :::CodeblockTabs Data points success response example ```json { "status": "SUCCESS", "evidenceId": "evidence_67890", "message": "Data points evidence successfully processed", "chargebacks": [ { "processorChargeId": "0073000000000096401767", "processorCaseNumber": "CB-43433343219", "orderId": "O6996685178152213554" } ] } ``` ::: :::CodeblockTabs Data points error response example ```json { "status": "FAILED", "message": "Invalid datapoints provided", "invalidEvidenceDatapoints": [ { "datapointPath": "proofsOfRefund[0].refundAmount", "failureReason": "Field must be a positive number" }, { "datapointPath": "proofsOfDelivery[0].trackingNumber", "failureReason": "Required field is missing" } ] } ``` ::: :::CodeblockTabs Files error response example ```json { "status": "FAILED", "message": "SCHEMA_VALIDATION_FAILED" } ``` :::