# 1. Create classification

<mark style="color:green;">`POST`</mark> `/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

<table><thead><tr><th width="174">Name</th><th width="101">Type</th><th width="104">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>string</td><td><code>true</code></td><td>A name for the classification.</td></tr><tr><td><code>description</code></td><td>string</td><td><code>false</code></td><td>A description for the classification.</td></tr><tr><td><code>documentTypes</code></td><td>object</td><td><code>true</code></td><td>An array of objects, each specifying a document type.</td></tr></tbody></table>

## 💡 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](https://docs.extracta.ai/document-classification-api/classification-details/document-types "mention") page.

## Body Example

```json
{
  "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

{% tabs %}
{% tab title="JavaScript" %}

```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();
```

{% endtab %}

{% tab title="Python" %}

```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)

```

{% endtab %}

{% tab title="PHP" %}

```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();
}

?>

```

{% endtab %}
{% endtabs %}

## Responses

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

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

{% endtab %}

{% tab title="500" %}

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

{% endtab %}
{% endtabs %}