Skip to main content

Download Document API

The download endpoints allow you to download documents. There are two methods available: getting a presigned download URL (POST) or directly downloading the file (GET).

Endpoints​

Method 1: Get Presigned Download URL​

POST /download

Returns a presigned URL that can be used to download the document. The URL is valid for 1 hour.

Method 2: Direct Download​

GET /download/:document_id

Directly downloads the document file with proper content type and filename headers.

Authentication​

Both endpoints require authentication using the access token obtained from generate-client-auth-token.

Include the token in the Authorization header:

Authorization: Bearer {access_token}

Request Headers​

HeaderRequiredDescription
AuthorizationYesBearer access_token from generate-client-auth-token
Content-TypeYesMust be application/json (for POST method)

Request Body (POST /download)​

{
  document_id: string;  // Required: Document identifier
}

Request Parameters​

document_id (required)​

  • Type: string
  • Description: Unique identifier for the document
  • Example: "doc-123" or "550e8400-e29b-41d4-a716-446655440000"

URL Parameters (GET /download/:document_id)​

document_id (required)​

  • Type: string (URL parameter)
  • Description: Unique identifier for the document
  • Example: "doc-123" or "550e8400-e29b-41d4-a716-446655440000"

Success Response​

POST /download - Presigned URL Response​

Status Code: 200

{
  statusCode: 200;
  data: {
    download_url: string;  // Presigned URL valid for 1 hour
  };
  message: "OKAY";
}

GET /download/:document_id - Direct Download Response​

Status Code: 200

Headers:

  • Content-Type: MIME type of the document (e.g., application/pdf)
  • Content-Disposition: attachment; filename="document-name.pdf"
  • Cache-Control: no-cache

Body: Binary file content

Error Responses​

Missing Required Fields (435)​

{
  statusCode: 435;
  data: {
  }
  message: "Document ID is required";
}

Unauthorized (403)​

{
  statusCode: 403;
  data: {
  }
  message: "UNAUTHORIZED";
}

Causes:

  • Missing or invalid Authorization header
  • Expired or invalid access token

Not Found (437)​

{
  statusCode: 437;
  data: {
  }
  message: "Document not found";
}

Causes:

  • Document with the provided document_id does not exist
  • Invalid document_id provided

Missing File Path (435)​

{
  statusCode: 435;
  data: {
  }
  message: "Document has no file path";
}

Causes:

  • Document is URL-based and doesn't have a file path
  • Document file was not uploaded

Server Fault (500)​

{
  statusCode: 500;
  data: {
  }
  message: "Failed to generate download URL";
}

or

{
  statusCode: 500;
  data: {
  }
  message: "Failed to download document";
}

Example Requests​

Example 1: Get Presigned Download URL​

This example shows getting a presigned URL for downloading:

# Step 1: Generate access token
curl -X POST https://api.example.com/generate-client-auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "fingerprint": "device-fingerprint-123",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "group_name": "my-domain"
    }
  }'

# Response:
# {
#   "statusCode": 200,
#   "data": {
#     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
#   },
#   "message": "OKAY"
# }

# Step 2: Get presigned download URL
curl -X POST https://api.example.com/download \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "document_id": "doc-abc-123-def-456"
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "download_url": "https://s3.amazonaws.com/bucket/documents/my-document.pdf?X-Amz-Algorithm=..."
  },
  "message": "OKAY"
}

Example 2: Direct Download​

This example shows directly downloading the document:

curl -X GET https://api.example.com/download/doc-abc-123-def-456 \
  -H "Authorization: Bearer {access_token}" \
  --output document.pdf

Behavior Notes​

Presigned URL Method (POST)​

  • Returns a presigned URL that can be used to download the document
  • URL is valid for 1 hour
  • Useful for sharing download links or downloading in a separate request
  • Works well for browser-based downloads

Direct Download Method (GET)​

  • Directly returns the file content
  • Includes proper content type and filename headers
  • Better for programmatic downloads
  • File is streamed directly to the client

File Types​

  • Supported file types include PDF, DOCX, TXT, and images (PNG, JPG, JPEG, GIF)
  • Content type is automatically determined based on file extension or document type
  • Filename includes proper extension

URL-Based Documents​

  • URL-based documents (documents with document_url but no document_file_path) cannot be downloaded via these endpoints
  • These endpoints only work for file-based documents