Get Documents

Overview

The Get Documents API allows you to retrieve a paginated list of documents associated with a business. Documents can include various types such as identification documents, bank statements, tax forms, contracts, licenses, and other business-related files. You can filter documents by type and verification status, and control pagination with limit and offset parameters. Results are ordered by creation date (newest first).

Resource Access

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

Path Parameters

Parameter	Type	Required	Description
business_id	string (UUID)	Yes	Unique identifier for the business

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of documents to return (default: 50, max: 100)
offset	integer	No	Number of documents to skip for pagination (default: 0)
type	string	No	Filter by document type: identification, bank_statement, tax_form, contract, license, other
status	string	No	Filter by verification status: pending, verified, rejected, expired

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)

{
  "documents": [
    {
      "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"
      },
      "created_at": "2022-01-01T00:00:00.000Z",
      "updated_at": "2022-01-01T12:00:00.000Z",
      "verified_at": "2022-01-01T01:30:00.000Z"
    },
    {
      "id": "urn:uuid:document-456",
      "business_id": "urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc",
      "filename": "bank_statement.pdf",
      "type": "bank_statement",
      "status": "pending",
      "mime_type": "application/pdf",
      "size_bytes": 1536000,
      "user_data": {
        "month": "December 2023",
        "account_type": "checking"
      },
      "created_at": "2022-01-02T00:00:00.000Z",
      "updated_at": "2022-01-02T00:00:00.000Z"
    }
  ],
  "total_count": 25,
  "limit": 10,
  "offset": 0
}

Response Fields

Field	Type	Description
documents	array	Array of document objects
documents[].id	string (UUID)	Unique identifier for the document
documents[].business_id	string (UUID)	Business ID this document belongs to
documents[].filename	string	Original filename of the uploaded document
documents[].type	string	Type of document
documents[].status	string	Verification status of the document
documents[].mime_type	string	MIME type of the document file
documents[].size_bytes	integer	Size of the document in bytes
documents[].user_data	object	Additional user-defined data
documents[].created_at	string (date-time)	Upload timestamp
documents[].updated_at	string (date-time)	Last update timestamp
documents[].verified_at	string (date-time)	Verification timestamp (verified documents only)
documents[].rejection_reason	string	Rejection reason (rejected documents only)
total_count	integer	Total number of documents matching the criteria
limit	integer	Number of documents returned in this response
offset	integer	Number of documents skipped

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

• 400 Bad Request: Invalid query parameters (e.g., invalid limit or offset)
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: User does not have permission to view documents for this business
• 404 Not Found: Business not found

Code Examples

cURL

curl -X GET \
  'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/documents?limit=10&type=identification&status=verified' \
  -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"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
params = {
    "limit": 10,
    "type": "identification",
    "status": "verified"
}

response = requests.get(url, headers=headers, params=params)
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';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const params = {
  limit: 10,
  type: 'identification',
  status: 'verified'
};

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

Usage Notes

• Results are ordered by creation date (newest first)
• Use limit and offset for pagination through large document collections
• Combine filters to narrow down results (e.g., type + status)
• The total_count field indicates the total number of documents matching your filters
• Maximum limit is 100 documents per request
• Default limit is 50 if not specified
• Use this API to monitor document verification status, generate compliance reports, or build document management interfaces
• The verified_at field is only included for documents with verified status
• The rejection_reason field is only included for documents with rejected status

Interactive API Explorer