API Basics

Request Headers

Always include these headers for optimal API performance:

Accept: application/json
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Response Format

API responses follow a consistent envelope. Two exceptions: a request with a missing, invalid or expired bearer token returns 403 with an empty body (not 401, and not JSON), and the token endpoint itself uses the OAuth 2.0 error format, for example {"error": "invalid_client"}.

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"
      ]
    }
  }
}

Order payloads that fail JSON Schema validation return SCHEMA_VALIDATION_ERROR with an errors array instead, one entry per field:

{
  "success": false,
  "error": {
    "code": "SCHEMA_VALIDATION_ERROR",
    "message": "Order payload validation failed",
    "errors": [
      { "field": "entity", "message": "entity is required", "type": "required" }
    ]
  }
}

Other codes you will see: NOT_FOUND (unknown route or record), INVALID_ID_FORMAT (a path id that is not a UUID; every resource id is a UUID), ACCESS_DENIED, PERMISSION_DENIED, THROTTLED, and UNKNOWN_ERROR for an unhandled server error.

Supported File Types

Documents can be uploaded to an entity or organization (POST /entities/{id}/documents/upload, multipart) or attached to an order in the document field of the order payload (base64 content, or a reference to an already uploaded document by id).

Supported Document Types

PDF files (.pdf)
Word files (.docx)

Other types, including images and .doc, are rejected with File type not supported. Allowed types: pdf, docx.

File Size Limits

Maximum file size: 50MB per document
One document per order payload

Rate Limits

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

Default Rate Limit:

120 requests per minute per API user, across all endpoints

There is no separate hourly allowance. Unauthenticated requests are rejected with 403 before rate limiting applies.

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 a second."
  }
}

The response carries a standard Retry-After header with the number of seconds to wait. There are no X-RateLimit-* headers.

Best Practices for Rate Limiting:

Honor Retry-After and back off when you receive 429 responses
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; larger values are capped at 1000)

Only these two parameters are recognized. page and cursor parameters are ignored. Unknown filter parameters are also ignored rather than rejected, so check total_count when a filter seems to have no effect.

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 with an explicit offset, for example 2026-04-14T08:23:01.998106-07:00. Parse the offset; do not assume UTC.
Identifiers: every resource id is a UUID string. Order responses also carry a human-readable order_id (for example 8L7RumBR-FDUOj541), but URLs take the UUID id.
Pagination: page_number and page_size only, as above