9 min read

REST API / cURL

Direct HTTP API integration with cURL examples

Integrate DocuRift directly using HTTP requests. This guide provides comprehensive cURL examples for all API endpoints.

Base URL

All API requests should be made to:

https://api.docurift.com/v1

Authentication

Include your API key in the X-API-Key header with every request:

curl -X GET https://api.docurift.com/v1/documents \
  -H "X-API-Key: frc_your_api_key_here"

API Key Format

  • Prefix: frc_ (DocuRift identifier)
  • Length: 36 characters total
  • Example: frc_abc123def456ghi789jkl012mno345pq

Security Best Practices

# Store API key in environment variable
export DOCURIFT_API_KEY="frc_your_api_key_here"

# Use in requests
curl -X GET https://api.docurift.com/v1/documents \
  -H "X-API-Key: $DOCURIFT_API_KEY"

Common Endpoints

Process Document (Synchronous)

Process a document and wait for the result. Best for small documents under 5 pages.

curl -X POST https://api.docurift.com/v1/documents/process/sync \
  -H "X-API-Key: $DOCURIFT_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "documentType=invoice"

Request Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file | File | Yes | Document file (PDF, JPG, PNG) | | documentType | string | No | Type: invoice, receipt, contract, bill_of_lading, packing_list, general |

Response:

{
  "success": true,
  "data": {
    "documentId": "doc_abc123xyz456",
    "status": "completed",
    "documentType": "invoice",
    "confidence": 0.97,
    "pagesProcessed": 2,
    "processedAt": "2024-01-26T10:30:00Z",
    "result": {
      "invoiceNumber": "INV-2024-001",
      "invoiceDate": "2024-01-15",
      "dueDate": "2024-02-15",
      "vendor": {
        "name": "Acme Shipping Co.",
        "address": "123 Harbor Blvd, Los Angeles, CA 90021",
        "taxId": "12-3456789"
      },
      "lineItems": [
        {
          "description": "Ocean Freight - Container 20ft",
          "quantity": 2,
          "unitPrice": 1500.00,
          "total": 3000.00
        }
      ],
      "subtotal": 3000.00,
      "taxAmount": 240.00,
      "totalAmount": 3240.00,
      "currency": "USD"
    }
  }
}

Process Document (Asynchronous)

Submit a document for processing and receive a job ID. Best for large documents or batch processing.

curl -X POST https://api.docurift.com/v1/documents/process/async \
  -H "X-API-Key: $DOCURIFT_API_KEY" \
  -F "file=@large-contract.pdf" \
  -F "documentType=contract" \
  -F "webhookUrl=https://your-server.com/webhooks/docurift"

Additional Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | webhookUrl | string | No | URL to receive completion webhook | | priority | string | No | low, normal, high |

Response:

{
  "success": true,
  "data": {
    "jobId": "job_xyz789abc123",
    "status": "pending",
    "estimatedTime": 30
  }
}

Check Job Status

Poll the status of an async processing job.

curl -X GET https://api.docurift.com/v1/jobs/job_xyz789abc123 \
  -H "X-API-Key: $DOCURIFT_API_KEY"

Response (Processing):

{
  "success": true,
  "data": {
    "jobId": "job_xyz789abc123",
    "status": "processing",
    "progress": 65,
    "createdAt": "2024-01-26T10:30:00Z"
  }
}

Response (Completed):

{
  "success": true,
  "data": {
    "jobId": "job_xyz789abc123",
    "documentId": "doc_abc123xyz456",
    "status": "completed",
    "createdAt": "2024-01-26T10:30:00Z",
    "completedAt": "2024-01-26T10:30:45Z",
    "result": {
      "invoiceNumber": "INV-2024-001",
      ...
    }
  }
}

Get Document

Retrieve a previously processed document by ID.

curl -X GET https://api.docurift.com/v1/documents/doc_abc123xyz456 \
  -H "X-API-Key: $DOCURIFT_API_KEY"

Response:

{
  "success": true,
  "data": {
    "documentId": "doc_abc123xyz456",
    "status": "completed",
    "documentType": "invoice",
    "confidence": 0.97,
    "pagesProcessed": 2,
    "createdAt": "2024-01-26T10:30:00Z",
    "result": {
      ...
    }
  }
}

List Documents

List all processed documents with pagination.

curl -X GET "https://api.docurift.com/v1/documents?limit=20&offset=0" \
  -H "X-API-Key: $DOCURIFT_API_KEY"

Query Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | limit | integer | 20 | Number of documents to return (max 100) | | offset | integer | 0 | Number of documents to skip | | status | string | - | Filter by status: completed, processing, failed | | documentType | string | - | Filter by document type |

Response:

{
  "success": true,
  "data": {
    "documents": [
      {
        "documentId": "doc_abc123xyz456",
        "status": "completed",
        "documentType": "invoice",
        "createdAt": "2024-01-26T10:30:00Z"
      },
      ...
    ],
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    }
  }
}

Delete Document

Delete a processed document and its data.

curl -X DELETE https://api.docurift.com/v1/documents/doc_abc123xyz456 \
  -H "X-API-Key: $DOCURIFT_API_KEY"

Response:

{
  "success": true,
  "data": {
    "documentId": "doc_abc123xyz456",
    "deleted": true
  }
}

Get Credit Balance

Check your current credit balance.

curl -X GET https://api.docurift.com/v1/credits/balance \
  -H "X-API-Key: $DOCURIFT_API_KEY"

Response:

{
  "success": true,
  "data": {
    "balance": 450,
    "used": 50,
    "limit": 500,
    "resetsAt": "2024-02-01T00:00:00Z",
    "plan": "pro"
  }
}

Get Credit Transactions

View credit usage history.

curl -X GET "https://api.docurift.com/v1/credits/transactions?limit=10" \
  -H "X-API-Key: $DOCURIFT_API_KEY"

Response:

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_123",
        "type": "usage",
        "amount": -2,
        "description": "Document processing: doc_abc123xyz456",
        "documentId": "doc_abc123xyz456",
        "createdAt": "2024-01-26T10:30:00Z"
      },
      {
        "id": "txn_122",
        "type": "purchase",
        "amount": 100,
        "description": "Credit purchase",
        "createdAt": "2024-01-20T15:00:00Z"
      }
    ],
    "pagination": {
      "total": 25,
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  }
}

Response Format

All API responses follow a consistent JSON structure.

Success Response

{
  "success": true,
  "data": {
    // Response data here
  }
}

Paginated Response

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "total": 100,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    }
  }
}

Error Responses

All errors follow a consistent format with descriptive error codes.

Error Response Structure

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Optional additional details
    }
  }
}

Common Error Codes

400 Bad Request

# Invalid file type
{
  "success": false,
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "File type not supported. Use PDF, JPG, or PNG."
  }
}

# File too large
{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds 10MB limit"
  }
}

# Validation error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid document type specified",
    "details": {
      "field": "documentType",
      "allowed": ["invoice", "receipt", "contract", "bill_of_lading", "packing_list", "general"]
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key. 20 attempts remaining before IP block."
  }
}

402 Payment Required

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Current balance: 0",
    "details": {
      "required": 2,
      "available": 0
    }
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "IP_BLOCKED",
    "message": "Your IP has been temporarily blocked due to multiple invalid API key attempts"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Document not found"
  }
}

429 Rate Limit Exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait 60 seconds.",
    "details": {
      "retryAfter": 60,
      "limit": 100,
      "window": "1h"
    }
  }
}

500 Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred. Please try again."
  }
}

Complete Workflow Examples

Synchronous Processing Script

#!/bin/bash

# Configuration
API_KEY="$DOCURIFT_API_KEY"
API_URL="https://api.docurift.com/v1"
FILE_PATH="$1"
DOC_TYPE="${2:-invoice}"

if [ -z "$FILE_PATH" ]; then
  echo "Usage: ./process.sh <file_path> [document_type]"
  exit 1
fi

if [ -z "$API_KEY" ]; then
  echo "Error: DOCURIFT_API_KEY environment variable not set"
  exit 1
fi

echo "Processing: $FILE_PATH"
echo "Document type: $DOC_TYPE"

# Process document
response=$(curl -s -X POST "$API_URL/documents/process/sync" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@$FILE_PATH" \
  -F "documentType=$DOC_TYPE")

# Check for success
success=$(echo "$response" | jq -r '.success')

if [ "$success" = "true" ]; then
  echo "Processing complete!"
  echo "$response" | jq '.data'
else
  echo "Error:"
  echo "$response" | jq '.error'
  exit 1
fi

Asynchronous Processing with Polling

#!/bin/bash

# Configuration
API_KEY="$DOCURIFT_API_KEY"
API_URL="https://api.docurift.com/v1"
FILE_PATH="$1"
DOC_TYPE="${2:-general}"
MAX_ATTEMPTS=30
POLL_INTERVAL=2

if [ -z "$FILE_PATH" ]; then
  echo "Usage: ./process-async.sh <file_path> [document_type]"
  exit 1
fi

# Submit for async processing
echo "Submitting document for processing..."
submit_response=$(curl -s -X POST "$API_URL/documents/process/async" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@$FILE_PATH" \
  -F "documentType=$DOC_TYPE")

job_id=$(echo "$submit_response" | jq -r '.data.jobId')

if [ "$job_id" = "null" ] || [ -z "$job_id" ]; then
  echo "Error submitting document:"
  echo "$submit_response" | jq '.error'
  exit 1
fi

echo "Job ID: $job_id"
echo "Polling for completion..."

# Poll for completion
for ((i=1; i<=MAX_ATTEMPTS; i++)); do
  status_response=$(curl -s -X GET "$API_URL/jobs/$job_id" \
    -H "X-API-Key: $API_KEY")

  status=$(echo "$status_response" | jq -r '.data.status')

  case "$status" in
    "completed")
      echo "Processing complete!"
      echo "$status_response" | jq '.data.result'
      exit 0
      ;;
    "failed")
      echo "Processing failed:"
      echo "$status_response" | jq '.data.error'
      exit 1
      ;;
    *)
      progress=$(echo "$status_response" | jq -r '.data.progress // "unknown"')
      echo "Status: $status (progress: $progress%) - attempt $i/$MAX_ATTEMPTS"
      sleep $POLL_INTERVAL
      ;;
  esac
done

echo "Timeout: Job did not complete within $((MAX_ATTEMPTS * POLL_INTERVAL)) seconds"
exit 1

Batch Processing

#!/bin/bash

# Configuration
API_KEY="$DOCURIFT_API_KEY"
API_URL="https://api.docurift.com/v1"
INPUT_DIR="$1"
OUTPUT_DIR="${2:-./output}"
DOC_TYPE="${3:-invoice}"

if [ -z "$INPUT_DIR" ]; then
  echo "Usage: ./batch-process.sh <input_directory> [output_directory] [document_type]"
  exit 1
fi

mkdir -p "$OUTPUT_DIR"

# Process each file
for file in "$INPUT_DIR"/*.{pdf,jpg,jpeg,png}; do
  [ -e "$file" ] || continue

  filename=$(basename "$file")
  output_file="$OUTPUT_DIR/${filename%.*}.json"

  echo "Processing: $filename"

  response=$(curl -s -X POST "$API_URL/documents/process/sync" \
    -H "X-API-Key: $API_KEY" \
    -F "file=@$file" \
    -F "documentType=$DOC_TYPE")

  success=$(echo "$response" | jq -r '.success')

  if [ "$success" = "true" ]; then
    echo "$response" | jq '.data' > "$output_file"
    echo "  -> Saved to: $output_file"
  else
    echo "  -> Error: $(echo "$response" | jq -r '.error.message')"
    echo "$response" > "$OUTPUT_DIR/${filename%.*}_error.json"
  fi

  # Respect rate limits
  sleep 1
done

echo "Batch processing complete!"

HTTP Headers Reference

Request Headers

| Header | Required | Description | |--------|----------|-------------| | X-API-Key | Yes | Your DocuRift API key | | Content-Type | Auto | Set automatically for multipart/form-data | | Accept | No | application/json (default) |

Response Headers

| Header | Description | |--------|-------------| | X-Request-Id | Unique request identifier for debugging | | X-RateLimit-Limit | Rate limit ceiling for your plan | | X-RateLimit-Remaining | Number of requests remaining | | X-RateLimit-Reset | Unix timestamp when limit resets |

Rate Limits

| Plan | Requests/Minute | Requests/Hour | |------|-----------------|---------------| | Free | 10 | 100 | | Pro | 60 | 1,000 | | Enterprise | 300 | 10,000 |

Rate limit headers are included in every response:

# Check remaining rate limit
curl -I -X GET https://api.docurift.com/v1/documents \
  -H "X-API-Key: $DOCURIFT_API_KEY" 2>&1 | grep -i "x-ratelimit"

Next Steps