Get Document

Overview

The Get Document API allows you to retrieve detailed information about a specific document by its ID. This endpoint returns the complete document object including all metadata, current verification status, and a temporary download URL for accessing the document file. The document must belong to the specified business and the authenticated user must have permission to view it.

Resource Access

• HTTP Method: GET
• Endpoint: /v1/businesses/{business_id}/documents/{document_id}
• Authentication: Bearer token required

Path Parameters

Parameter	Type	Required	Description
business_id	string (UUID)	Yes	Unique identifier for the business
document_id	string (UUID)	Yes	Unique identifier for the document to retrieve

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication

Response

Success Response (200 OK)

{
  "id": "urn:uuid:document-123",
  "business_id": "urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc",
  "filename": "drivers_license.pdf",
  "type": "identification",
  "status": "verified",
  "mime_type": "application/pdf",
  "size_bytes": 2048576,
  "user_data": {
    "purpose": "Identity verification",
    "expiry_date": "2025-12-31",
    "notes": "Additional document notes"
  },
  "created_at": "2022-01-01T00:00:00.000Z",
  "updated_at": "2022-01-01T12:00:00.000Z",
  "verified_at": "2022-01-01T01:30:00.000Z",
  "download_url": "https://api.example.com/v1/documents/urn:uuid:document-123/download?token=abc123"
}

Response Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the document
business_id	string (UUID)	Business ID this document belongs to
filename	string	Original filename of the uploaded document
type	string	Type of document
status	string	Verification status of the document
mime_type	string	MIME type of the document file
size_bytes	integer	Size of the document in bytes
user_data	object	Additional user-defined data
created_at	string (date-time)	Upload timestamp
updated_at	string (date-time)	Last update timestamp
verified_at	string (date-time)	Verification timestamp (verified documents only)
rejected_at	string (date-time)	Rejection timestamp (rejected documents only)
rejection_reason	string	Reason for rejection (rejected documents only)
download_url	string (URI)	Temporary URL to download the document file

Document Type Values

• identification: Government-issued ID, passport, driver's license
• bank_statement: Bank account statements and transaction history
• tax_form: Tax returns, W-9 forms, tax documents
• contract: Legal contracts and agreements
• license: Business licenses and permits
• other: Miscellaneous business documents

Document Status Values

• pending: Document uploaded but not yet reviewed
• verified: Document has been verified and approved
• rejected: Document was rejected during verification
• expired: Document was previously verified but has expired

Error Responses

• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: User does not have permission to view this document
• 404 Not Found: Business or document not found

Code Examples

cURL

curl -X GET \
  'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/documents/urn:uuid:document-123' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Python

import requests

url = "https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/documents/urn:uuid:document-123"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/documents/urn:uuid:document-123';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};

axios.get(url, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Use this endpoint to check the current status of a specific document
• The download_url provides temporary access to the actual document file (typically expires in minutes/hours)
• The verified_at field is only included for documents with verified status
• The rejected_at and rejection_reason fields are only included for documents with rejected status
• This endpoint provides more detailed information than the list documents endpoint
• Use the document ID from upload responses or list documents results
• The authenticated user must have permission to view documents for the specified business
• Document details include all metadata and processing information for monitoring and auditing

Downloading Documents

To download the actual document file, use the download_url provided in the response:

curl -X GET \
  'https://api.example.com/v1/documents/urn:uuid:document-123/download?token=abc123' \
  -o drivers_license.pdf

Note: Download URLs are temporary and will expire. Always retrieve a fresh download URL before attempting to download.

Interactive API Explorer