Reporting Setup - API Workflow Guide

This guide provides a complete workflow for API developers to integrate with Flextract's document processing and reporting system. Follow these steps to set up new clients, upload documents, and generate JSON reports.

Authentication
New Client Setup
Document Upload
Report Generation
Complete Example Workflow
Error Handling

Authentication

Flextract uses JWT token authentication (others available, see Authentation) for API access. All API requests must include an Authorization header with a valid JWT token.

Authorization: Bearer <your_jwt_token>

Getting a JWT Token

curl -X POST https://api.flextract.dev/api/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

🗒️
If you'd like a 'system' account, please email [email protected] and we'd be happy to set you up!

Response:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

New Client Setup

When a new client signs up, you need to create a folder and set up folder linking for document routing.

1. Create Folder

Create a folder to organize the client's documents:

curl -X POST https://api.flextract.dev/api/folders/ \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Name - 2024",
    "description": "Documents for Client Name"
  }'

Response:

{
  "hashid": "abc123def",
  "name": "Client Name - 2024",
  "description": "Documents for Client Name",
  "parent_folder": null,
  "organization": "org456ghi",
  "document_count": 0,
  "last_activity": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

2. Create Folder Link

Link the client's phone number to the folder for automatic document routing:

curl -X POST https://api.flextract.dev/api/folder-links/ \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "folder": "abc123def",
    "phone_number_raw": "+1234567890"
  }'

Response:

{
  "hashid": "link789xyz",
  "folder": "abc123def",
  "phone_number": 123,
  "user": null,
  "created_at": "2024-01-15T10:35:00Z"
}

Document Upload

There are two ways to upload documents: authenticated API upload and client portal upload.

Method 1: Authenticated API Upload

Upload documents directly using your API token:

curl -X POST https://api.flextract.dev/api/docs/ \
  -H "Authorization: Bearer <your_jwt_token>" \
  -F "file=@/path/to/document.pdf" \
  -F "folder_id=abc123def" \
  -F "pipeline_name=V1-Pipeline"

Response:

{
  "id": "doc456ghi",
  "name": "document.pdf",
  "status": "pending",
  "folder": "abc123def",
  "created_at": "2024-01-15T11:00:00Z",
  "reference_id": "REF789012"
}

Method 2: Client Portal Upload

Clients can also upload documents directly through the Flextract client portal. When a folder link is created with the client's phone number (as shown in the setup section), documents uploaded by the client through the portal will automatically be routed to the correct folder. This provides a user-friendly interface for clients.

Report Generation

Generate comprehensive JSON reports from processed documents in a folder.

1. List Available Reports

First, get a list of available report templates:

curl -X GET https://api.flextract.dev/api/reports/ \
  -H "Authorization: Bearer <your_jwt_token>"

Response:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "hashid": "report123abc",
      "name": "Financial Statement Analysis",
      "description": "Comprehensive financial analysis report",
      "organization": null,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "hashid": "report456def",
      "name": "Tax Document Summary",
      "description": "Summary of tax-related documents",
      "organization": null,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

2. Generate Report Based on Folder

Create a report using documents from a specific folder:

curl -X POST https://api.flextract.dev/api/reports/report123abc/ \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "abc123def"
  }'

Response:

{
  "hashid": "instance789ghi",
  "report": "report123abc",
  "status": "processing",
  "created_at": "2024-01-15T12:00:00Z",
}

3. Get Report Status

Check the status of your report generation:

curl -X GET https://api.flextract.dev/api/reports/instance789ghi/ \
  -H "Authorization: Bearer <your_jwt_token>"

Response:

{
  "hashid": "instance789ghi",
  "report": "report123abc",
  "status": "completed",
  "created_at": "2024-01-15T12:00:00Z",
  "completed_at": "2024-01-15T12:04:30Z"
}

4. Get Report JSON Data

Once the report is completed, retrieve the JSON data:

curl -X GET https://api.flextract.dev/api/reports/instance789ghi/json/ \
  -H "Authorization: Bearer <your_jwt_token>"

Response:

{
  "report_id": "instance789ghi",
  "report_name": "Financial Statement Analysis",
  "generated_at": "2024-01-15T12:04:30Z",
  "folder": {
    "id": "abc123def",
    "name": "Client Name - 2024",
    "document_count": 5
  },
  "data": {
    "financial_summary": {
      "total_revenue": 1250000,
      "total_expenses": 980000,
      "net_income": 270000,
      "assets": {
        "current_assets": 450000,
        "fixed_assets": 800000,
        "total_assets": 1250000
      },
      "liabilities": {
        "current_liabilities": 200000,
        "long_term_liabilities": 350000,
        "total_liabilities": 550000
      },
      "equity": 700000
    },
    "ratios": {
      "current_ratio": 2.25,
      "debt_to_equity": 0.79,
      "return_on_assets": 0.216,
      "profit_margin": 0.216
    },
    "documents_analyzed": [
      {
        "id": "doc456ghi",
        "name": "balance_sheet_2024.pdf",
        "type": "Balance Sheet",
        "confidence": 0.95
      },
      {
        "id": "doc789xyz",
        "name": "income_statement_2024.pdf",
        "type": "Income Statement",
        "confidence": 0.92
      }
    ]
  }
}

Complete Example Workflow

Here's a complete example workflow for setting up a new client and generating a report:

#!/bin/bash

# Configuration
API_BASE="https://api.flextract.dev/api"
JWT_TOKEN="your_jwt_token_here"
CLIENT_NAME="Acme Corporation"
CLIENT_PHONE="+1234567890"
SUBDOMAIN="your-org-subdomain"

# Step 1: Create folder for client
echo "Creating folder for $CLIENT_NAME..."
FOLDER_RESPONSE=$(curl -s -X POST "$API_BASE/folders/" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$CLIENT_NAME - 2024\", \"description\": \"Documents for $CLIENT_NAME\"}")

FOLDER_ID=$(echo $FOLDER_RESPONSE | jq -r '.hashid')
echo "Created folder with ID: $FOLDER_ID"

# Step 2: Create folder link
echo "Linking phone number to folder..."
LINK_RESPONSE=$(curl -s -X POST "$API_BASE/folder-links/" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"folder\": \"$FOLDER_ID\", \"phone_number_raw\": \"$CLIENT_PHONE\"}")

echo "Folder link created successfully"

# Step 3: Upload a document (example)
echo "Uploading sample document..."
DOC_RESPONSE=$(curl -s -X POST "$API_BASE/docs/" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -F "file=@sample_document.pdf" \
  -F "folder_id=$FOLDER_ID" \
  -F "pipeline_name=V1-Pipeline")

DOC_ID=$(echo $DOC_RESPONSE | jq -r '.reference_id')
echo "Document uploaded with reference ID: $DOC_ID"

# Step 4: Wait for document processing (in practice, you'd poll or use webhooks)
echo "Waiting for document processing..."
sleep 30

# Step 5: List available reports
echo "Getting available reports..."
REPORTS_RESPONSE=$(curl -s -X GET "$API_BASE/reports/" \
  -H "Authorization: Bearer $JWT_TOKEN")

REPORT_ID=$(echo $REPORTS_RESPONSE | jq -r '.results[0].hashid')
echo "Using report template: $REPORT_ID"

# Step 6: Generate report
echo "Generating report..."
REPORT_INSTANCE_RESPONSE=$(curl -s -X POST "$API_BASE/reports/$REPORT_ID/" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"folder_id\": \"$FOLDER_ID\", \"async\": true}")

INSTANCE_ID=$(echo $REPORT_INSTANCE_RESPONSE | jq -r '.hashid')
echo "Report generation started with instance ID: $INSTANCE_ID"

# Step 7: Poll for completion
echo "Waiting for report completion..."
while true; do
  STATUS_RESPONSE=$(curl -s -X GET "$API_BASE/reports/$INSTANCE_ID/" \
    -H "Authorization: Bearer $JWT_TOKEN")
  
  STATUS=$(echo $STATUS_RESPONSE | jq -r '.status')
  echo "Report status: $STATUS"
  
  if [ "$STATUS" = "completed" ]; then
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Report generation failed"
    exit 1
  fi
  
  sleep 10
done

# Step 8: Get JSON report
echo "Retrieving JSON report..."
JSON_REPORT=$(curl -s -X GET "$API_BASE/reports/$INSTANCE_ID/json/" \
  -H "Authorization: Bearer $JWT_TOKEN")

echo "Report generated successfully!"
echo $JSON_REPORT | jq '.'

Error Handling

All API endpoints return standardized error responses following the JSON:API specification:

Error Response Format

{
  "errors": [
    {
      "status": "400",
      "code": "validation_error",
      "title": "Validation Error",
      "detail": "The provided data is invalid",
      "source": {
        "pointer": "/data/attributes/phone_number"
      }
    }
  ]
}

Common Error Codes

Status Code	Description	Common Causes
400	Bad Request	Invalid request data, missing required fields
401	Unauthorized	Invalid or expired JWT token
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist or user doesn't have access
422	Unprocessable Entity	Valid request format but business logic validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Error Handling Best Practices

Always check HTTP status codes before processing response data
Parse error responses to get detailed error information
Implement retry logic for 5xx errors and 429 rate limiting
Log errors for debugging and monitoring
Provide meaningful error messages to end users

Example Error Handling

# Example with error handling
RESPONSE=$(curl -s -w "%{http_code}" -X POST "$API_BASE/folders/" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Folder"}')

HTTP_CODE="${RESPONSE: -3}"
BODY="${RESPONSE%???}"

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
  echo "Success: $BODY"
else
  echo "Error ($HTTP_CODE): $BODY"
  ERROR_DETAIL=$(echo $BODY | jq -r '.errors[0].detail // "Unknown error"')
  echo "Error detail: $ERROR_DETAIL"
fi

Rate Limits

The Flextract API implements rate limiting to ensure fair usage:

Standard endpoints: 1000 requests per hour per user
Upload endpoints: 100 requests per hour per user
Report generation: 50 requests per hour per user

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642694400

Support

For additional support or questions about the API:

Documentation: https://docs.flextract.dev
API Reference: https://api.flextract.dev/api-docs/schema/swagger-ui/
Support Email: [email protected]
Status Page: https://status.flextract.dev

Changelog

Version 1.0.0 (2025-07-22)

Initial API workflow documentation
Complete client setup workflow
Document upload methods
Report generation process
Error handling guidelines

Table of Contents

Authentication

Getting a JWT Token

If you'd like a 'system' account, please email [email protected] and we'd be happy to set you up!

New Client Setup

1. Create Folder

2. Create Folder Link

Document Upload

Method 1: Authenticated API Upload

Method 2: Client Portal Upload

Report Generation

1. List Available Reports

2. Generate Report Based on Folder

3. Get Report Status

4. Get Report JSON Data

Complete Example Workflow

Error Handling

Error Response Format

Common Error Codes

Error Handling Best Practices

Example Error Handling

Rate Limits

Support

Changelog

Version 1.0.0 (2025-07-22)