API Basics

Request Headers

Always include these headers for optimal API performance:

Accept: application/json
Content-Type: application/json
Authentication: "Bearer YOUR_API_TOKEN"

Response Format

All API responses follow a consistent structure:

Success Response:

{
  "success": true,
  "data": { ... }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid order ID",
    "validation_errors": {
      "non_field_errors": [
        "Invalid order ID"
      ]
    }
  }
}

Supported File Types

The API supports various document types for upload and attachment to orders. These documents are used to provide supporting information that can reduce the number of required fields in order payloads and help streamline the order processing workflow.

Supported Document Types

PDF files (.pdf)
Image files (.jpg, .jpeg, .png, .gif)
Document files (.doc, .docx)

File Size Limits

Maximum file size: 10MB per document
Maximum total attachments per order: 1 document

Rate Limits

The SingleFile API implements rate limiting to ensure fair usage and maintain service quality.

Default Rate Limits:

User Rate Limit: 1000 requests per hour per user
Burst Rate Limit: 60 requests per minute per user
Anonymous Rate Limit: 100 requests per hour per IP address

Rate Limit Response: When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "code": "THROTTLED",
    "message": "Request was throttled. Expected available in 60 seconds.",
    "retry_after": 60
  }
}

Best Practices for Rate Limiting:

Implement exponential backoff when you receive 429 responses
Monitor rate limit headers to track your usage
Cache responses when possible to reduce API calls
Batch operations to minimize the number of requests
Use webhooks instead of polling for real-time updates

Pagination

List endpoints support pagination with these parameters:

page_number: Page number (starts from 1)
page_size: Number of results per page (max 1000, default 10)

Pagination Response:

{
  "success": true,
  "data": [...],
  "total_pages": 8,
  "total_count": 150,
  "page_number": 1
}

Conventions

Data Format: JSON in/out unless otherwise specified
Timestamps: ISO-8601 UTC format
Pagination: May include page, page_size, or cursors if provided by the API