Templates API

Manage document extraction templates through the API.

Create Template

Create a new template for document data extraction.

POST /documents/templates

Request Body

{
  "name": "Standard Invoice Template",
  "documentType": "invoice",
  "format": "fixed|variable",
  "version": "1.0",
  "matchingRules": {
    "contentMatches": ["INVOICE", "Invoice Number"],
    "documentType": "invoice"
  },
  "fields": [
    {
      "name": "invoice_number",
      "type": "TEXT|NUMBER|DATE|BOOLEAN|SELECT|MULTISELECT",
      "page": 1,
      "positionX": 400,
      "positionY": 150,
      "width": 120,
      "height": 20,
      "required": true,
      "ediSegment": "BIG",
      "ediElement": "BIG02"
    }
  ],
  "validationSchema": {
    "invoice_number": {
      "pattern": "^INV-\\d+$",
      "required": true
    }
  },
  "outputMapping": {
    "invoice_number": "$.invoice.number"
  },
  "sampleFile": {
    "fileName": "sample.pdf",
    "data": "base64-encoded-file-content",
    "contentType": "application/pdf"
  }
}

Response

{
  "success": true,
  "data": {
    "id": "tpl_abc123",
    "name": "Standard Invoice Template",
    "documentType": "invoice",
    "format": "fixed",
    "version": "1.0",
    "status": "active",
    "createdAt": "2024-01-15T10:30:00Z",
    "fieldsCount": 6
  }
}

List Templates

Retrieve all templates with optional filtering.

GET /documents/templates

Query Parameters

Parameter	Type	Description
`type`	string	Filter by document type
`status`	string	Filter by status (active, inactive)
`limit`	integer	Number of results (max 100)
`offset`	integer	Pagination offset

Request

GET /documents/templates?type=invoice&status=active&limit=10

Response

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "tpl_abc123",
        "name": "Standard Invoice Template",
        "documentType": "invoice",
        "format": "variable",
        "version": "1.0",
        "status": "active",
        "fieldsCount": 6,
        "accuracy": 0.94,
        "lastUsed": "2024-01-15T14:30:00Z",
        "createdAt": "2024-01-10T09:00:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25
    }
  }
}

Get Template

Retrieve a specific template with full details.

GET /documents/templates/{id}

Response

{
  "success": true,
  "data": {
    "id": "tpl_abc123",
    "name": "Standard Invoice Template",
    "documentType": "invoice",
    "format": "variable",
    "version": "1.0",
    "status": "active",
    "matchingRules": {
      "contentMatches": ["INVOICE", "Invoice Number"],
      "documentType": "invoice",
      "confidence": 0.8
    },
    "fields": [
      {
        "id": "fld_123",
        "name": "invoice_number",
        "type": "TEXT",
        "page": 1,
        "positionX": 400,
        "positionY": 150,
        "width": 120,
        "height": 20,
        "required": true,
        "ediSegment": "BIG",
        "ediElement": "BIG02"
      }
    ],
    "validationSchema": {
      "invoice_number": {
        "pattern": "^INV-\\d+$",
        "required": true
      }
    },
    "outputMapping": {
      "invoice_number": "$.invoice.number"
    },
    "statistics": {
      "documentsProcessed": 1250,
      "averageAccuracy": 0.94,
      "averageProcessingTime": "2.3s",
      "successRate": 0.96
    },
    "createdAt": "2024-01-10T09:00:00Z",
    "updatedAt": "2024-01-12T15:45:00Z"
  }
}

Update Template

Update an existing template.

PUT /documents/templates/{id}

Request Body

{
  "name": "Enhanced Invoice Template",
  "fields": [
    {
      "name": "vendor_name",
      "type": "TEXT",
      "page": 1,
      "positionX": 50,
      "positionY": 100,
      "width": 200,
      "height": 25,
      "required": true
    }
  ],
  "validationSchema": {
    "vendor_name": {
      "minLength": 2,
      "maxLength": 100
    }
  }
}

Response

{
  "success": true,
  "data": {
    "id": "tpl_abc123",
    "name": "Enhanced Invoice Template",
    "version": "1.1",
    "fieldsCount": 7,
    "updatedAt": "2024-01-15T16:20:00Z"
  }
}

Delete Template

Delete a template permanently.

DELETE /documents/templates/{id}

Response

{
  "success": true,
  "message": "Template deleted successfully"
}

Test Template

Test a template against sample documents.

POST /documents/templates/{id}/test

Request Body

{
  "documentUrls": [
    "https://your-domain.com/sample1.pdf",
    "https://your-domain.com/sample2.pdf"
  ],
  "returnExtractedData": true,
  "includeConfidenceScores": true
}

Response

{
  "success": true,
  "data": {
    "testResults": [
      {
        "documentUrl": "https://your-domain.com/sample1.pdf",
        "success": true,
        "extractedData": {
          "invoice_number": "INV-2024-001",
          "total_amount": 1250.00,
          "vendor_name": "Acme Corp"
        },
        "confidence": {
          "overall": 0.96,
          "fields": {
            "invoice_number": 0.99,
            "total_amount": 0.94,
            "vendor_name": 0.95
          }
        },
        "processingTime": "1.2s"
      }
    ],
    "summary": {
      "averageAccuracy": 0.94,
      "successRate": 1.0,
      "averageProcessingTime": "1.4s"
    }
  }
}

Match Template

Find the best template match for a document.

POST /documents/templates/match

Request Body

{
  "documentId": "doc_xyz789",
  "documentType": "invoice",
  "returnConfidence": true,
  "maxResults": 5
}

Response

{
  "success": true,
  "data": {
    "matches": [
      {
        "templateId": "tpl_abc123",
        "templateName": "Standard Invoice Template",
        "confidence": 0.92,
        "matchReason": "Content and layout match"
      },
      {
        "templateId": "tpl_def456",
        "templateName": "Vendor Specific Invoice",
        "confidence": 0.78,
        "matchReason": "Partial content match"
      }
    ],
    "bestMatch": {
      "templateId": "tpl_abc123",
      "confidence": 0.92
    }
  }
}

Template Analytics

Get detailed analytics for template performance.

GET /documents/templates/{id}/analytics

Query Parameters

Parameter	Type	Description
`period`	string	Time period (1d, 7d, 30d, 90d)
`metrics`	string	Comma-separated metrics to include

Response

{
  "success": true,
  "data": {
    "templateId": "tpl_abc123",
    "period": "30d",
    "metrics": {
      "documentsProcessed": 1250,
      "averageAccuracy": 0.94,
      "averageProcessingTime": "2.3s",
      "successRate": 0.96,
      "errorRate": 0.04
    },
    "fieldMetrics": {
      "invoice_number": {
        "accuracy": 0.99,
        "extractionRate": 0.98,
        "avgConfidence": 0.97
      },
      "total_amount": {
        "accuracy": 0.91,
        "extractionRate": 0.94,
        "avgConfidence": 0.89
      }
    },
    "trends": {
      "accuracyTrend": "improving",
      "volumeTrend": "increasing",
      "errorTrend": "decreasing"
    },
    "commonErrors": [
      {
        "field": "total_amount",
        "error": "Format validation failed",
        "frequency": 12,
        "percentage": 0.96
      }
    ]
  }
}

Clone Template

Create a copy of an existing template.

POST /documents/templates/{id}/clone

Request Body

{
  "name": "Cloned Invoice Template",
  "documentType": "invoice"
}

Response

{
  "success": true,
  "data": {
    "id": "tpl_xyz789",
    "name": "Cloned Invoice Template",
    "clonedFrom": "tpl_abc123",
    "createdAt": "2024-01-15T17:00:00Z"
  }
}

Field Types

TEXT

Extract text content like names, addresses, descriptions.

NUMBER

Extract numeric values including integers and decimals.

DATE

Extract dates in various formats with automatic normalization.

BOOLEAN

Extract true/false values from checkboxes or yes/no fields.

SELECT

Extract single values from predefined options.

MULTISELECT

Extract multiple values from a list of options.

Error Codes

Code	Description
`TEMPLATE_NOT_FOUND`	Template ID doesn't exist
`INVALID_FIELD_TYPE`	Unsupported field type specified
`VALIDATION_ERROR`	Request validation failed
`TEMPLATE_IN_USE`	Cannot delete template currently in use
`FIELD_POSITION_INVALID`	Field coordinates are outside page bounds
`DUPLICATE_FIELD_NAME`	Field name already exists in template

Templates API

On this page