Retrieve a document

GEThttps://api.omise.co/disputes/:id/documents/:document_id

Retrieve a specific document from a dispute. This endpoint returns detailed information about an evidence file, including the download URL to access the file.

Request Parameters

Required - 2 fieldsRequired Parameters

▼

`id`STRING(required)

Dispute ID (path parameter).

Example:"dspt_test_5xuy4w91xqz7d1w9u0t"

`document_id`STRING(required)

Document ID to retrieve (path parameter). Format: docu_test_ or docu_live_ followed by alphanumeric string.

Example:"docu_test_5xuy4w91xqz7d1w9u0t"

---

Responses

200

Successful retrieval

Returns the document object with complete details including download URL.

Response includes:

• object - Always "document"
• id - Document ID (docu_*)
• livemode - Whether this is a live mode document
• location - API path to retrieve the document
• deleted - Whether the document has been deleted
• filename - Original filename
• kind - Document type (cardholder_details, details_of_purchase, proof_of_receipt, proof_of_acceptance)
• download_uri - Temporary URL to download the document
• created_at - When the document was uploaded

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid dispute ID format
• Invalid document ID format

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Dispute or document not found.

Common causes:

• Incorrect dispute ID
• Incorrect document ID
• Document does not belong to this dispute
• Dispute or document belongs to different account
• ID typo or formatting error

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/disputes/dspt_test_5xuy4w91xqz7d1w9u0t/documents/docu_test_5xuy4w91xqz7d1w9u0t \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

document = Omise::Document.retrieve(
  'dspt_test_5xuy4w91xqz7d1w9u0t',
  'docu_test_5xuy4w91xqz7d1w9u0t'
)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

document = omise.Document.retrieve(
    'dspt_test_5xuy4w91xqz7d1w9u0t',
    'docu_test_5xuy4w91xqz7d1w9u0t'
)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const document = await omise.documents.retrieve(
  'dspt_test_5xuy4w91xqz7d1w9u0t',
  'docu_test_5xuy4w91xqz7d1w9u0t'
);

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$document = OmiseDocument::retrieve(
    'dspt_test_5xuy4w91xqz7d1w9u0t',
    'docu_test_5xuy4w91xqz7d1w9u0t'
);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Document document = client.documents().retrieve(
    "dspt_test_5xuy4w91xqz7d1w9u0t",
    "docu_test_5xuy4w91xqz7d1w9u0t"
);

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var document = await client.Documents.Retrieve(
    "dspt_test_5xuy4w91xqz7d1w9u0t",
    "docu_test_5xuy4w91xqz7d1w9u0t"
);

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

document, _ := client.Document.Retrieve(
    "dspt_test_5xuy4w91xqz7d1w9u0t",
    "docu_test_5xuy4w91xqz7d1w9u0t",
)

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Document not found	Check both dispute ID and document ID are correct
invalid_document_id	Document ID format invalid	Use valid docu_ format

Download URL Notes

• The download_uri is a temporary signed URL
• URL expires after a period (typically 15 minutes to 1 hour)
• Request a new document retrieval to get a fresh download URL if expired

---

🔑API Credentials

▼

Try it out

Required - 2 fields

▼

id(Required)

document_id(Required)

Your IP: ...Loading...