# 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 ` |
## 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](/document-classification-api/classification-details/document-types.md) 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
$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 %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.extracta.ai/document-classification-api/api-endpoints-document-classification/1.-create-classification.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.