1. Create classification

POST /documentClassification/createClassification

Initiates a new document classification process. This endpoint allows you to define a classification with a list of possible document types. Once created, you can use the returned classificationId to upload documents for type prediction.

Server URL

https://api.extracta.ai/api/v1

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Required	Description
name	string	true	A name for the classification.
description	string	false	A description for the classification.
documentTypes	object	true	An array of objects, each specifying a document type.

💡 Need help defining documentTypes?

Each item in the documentTypes array represents a document category used for classification (e.g., Invoice, Receipt). To learn how to properly define a document type — including required fields, keyword strategy, and optional data extraction linkage — refer to the Document Types page.

Body Example

{
  "classificationDetails": {
    "name": "Financial Document Classifier",
    "description": "Classifies uploaded documents into predefined financial document types.",
    "documentTypes": [
      {
        "name": "Invoice",
        "description": "Standard commercial invoice from vendors or suppliers.",
        "uniqueWords": ["invoice number", "bill to", "total amount"],
        "extractionId": "invoiceExtractionId"
      },
      {
        "name": "Purchase Order",
        "description": "Internal or external purchase order documents.",
        "uniqueWords": ["PO number", "item description", "quantity ordered"]
      },
      {
        "name": "Receipt",
        "description": "Retail or online transaction receipts.",
        "uniqueWords": ["receipt", "paid", "transaction id"]
      }
    ]
  }
}

Code Example

JavaScript

const axios = require('axios');

async function createClassification(token, classificationDetails) {
    const url = "https://api.extracta.ai/api/v1/documentClassification/createClassification";

    try {
        const response = await axios.post(url, {
            classificationDetails: classificationDetails
        }, {
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${token}`
            }
        });

        return response.data;
    } catch (error) {
        throw error.response ? error.response.data : new Error('An unknown error occurred');
    }
}

async function main() {
    const token = 'apiKey';
    const classificationDetails = {
        name: "Financial Documents Classifier",
        description: "Classifies invoices, receipts, and purchase orders.",
        documentTypes: [
            {
                name: "Invoice",
                description: "Documents with billing and totals for payment.",
                uniqueWords: ["invoice number", "bill to", "total amount"],
                extractionId: "invoiceExtractionId"
            },
            {
                name: "Receipt",
                description: "Confirmation of payment or transaction.",
                uniqueWords: ["receipt", "paid", "transaction id"]
            },
            {
                name: "Purchase Order",
                description: "Authorizes a purchase transaction.",
                uniqueWords: ["PO number", "item", "quantity ordered"]
            }
        ]
    };

    try {
        const response = await createClassification(token, classificationDetails);
        console.log("New Classification Created:", response);
    } catch (error) {
        console.error("Failed to create classification:", error);
    }
}

main();

Python

import requests


def create_classification(token, classification_details):
    url = "https://api.extracta.ai/api/v1/documentClassification/createClassification"
    headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"}

    try:
        response = requests.post(url, json={"classificationDetails": classification_details}, headers=headers)
        response.raise_for_status()
        return response.json()
    except requests.RequestException as e:
        print(e)
        return None


if __name__ == "__main__":
    token = "apiKey"
    classification_details = {
        "name": "Financial Documents Classifier",
        "description": "Classifies invoices, receipts, and purchase orders.",
        "documentTypes": [
            {
                "name": "Invoice",
                "description": "Documents with billing and totals for payment.",
                "uniqueWords": ["invoice number", "bill to", "total amount"],
                "extractionId": "invoiceExtractionId"
            },
            {
                "name": "Receipt",
                "description": "Confirmation of payment or transaction.",
                "uniqueWords": ["receipt", "paid", "transaction id"]
            },
            {
                "name": "Purchase Order",
                "description": "Authorizes a purchase transaction.",
                "uniqueWords": ["PO number", "item", "quantity ordered"]
            }
        ]
    }

    response = create_classification(token, classification_details)
    print("New Classification Created:", response)

PHP

<?php

function createClassification($token, $classificationDetails) {
    $url = 'https://api.extracta.ai/api/v1/documentClassification/createClassification';

    // Initialize cURL session
    $ch = curl_init($url);

    // Prepare the payload
    $payload = json_encode(['classificationDetails' => $classificationDetails]);

    // Set cURL options
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $token,
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, 1);

    try {
        $response = curl_exec($ch);

        if (curl_errno($ch)) {
            throw new Exception('Curl error: ' . curl_error($ch));
        }

        return $response;
    } catch (Exception $e) {
        return 'Error: ' . $e->getMessage();
    } finally {
        curl_close($ch);
    }
}

// Example usage
$token = 'apiKey';
$classificationDetails = [
    "name" => "Financial Documents Classifier",
    "description" => "Classifies invoices, receipts, and purchase orders.",
    "documentTypes" => [
        [
            "name" => "Invoice",
            "description" => "Documents with billing and totals for payment.",
            "uniqueWords" => ["invoice number", "bill to", "total amount"],
            "extractionId" => "invoiceExtractionId"
        ],
        [
            "name" => "Receipt",
            "description" => "Confirmation of payment or transaction.",
            "uniqueWords" => ["receipt", "paid", "transaction id"]
        ],
        [
            "name" => "Purchase Order",
            "description" => "Authorizes a purchase transaction.",
            "uniqueWords" => ["PO number", "item", "quantity ordered"]
        ]
    ]
];

try {
    $response = createClassification($token, $classificationDetails);
    echo $response;
} catch (Exception $e) {
    echo "Failed to create new classification: " . $e->getMessage();
}

?>

Responses

200

{
    "status": "created",
    "createdAt": 1712547789609,
    "classificationId": "classificationId"
}

400

{
    "status": "error",
    "message": "Name is required"
}

500

{
    "status": "error",
    "message": "Error creating classification"
}