5. Upload Files

POST /uploadFiles

This endpoint enables users to upload files to a specified extraction. If a batchId is included in the request, the files will be added to that specific existing batch on the platform. It is important to ensure that the batchId already exists; otherwise, the upload will not be successful. If no batchId is provided in the request, a new batch will automatically be created for the files.

Files must be uploaded using the multipart/form-data content type, which is suitable for uploading binary files (like documents and images).

Postman Collection

For a complete and interactive set of API requests, please refer to our Postman Integrationcollection.

Server URL

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

Headers

Name	Value
Content-Type	multipart/form-data
Authorization	Bearer <token>

Body

Name	Type	Required	Description
extractionId	string	true	Unique identifier for the extraction.
batchId	string	false	The ID of the batch to add files to.
files	multipart	true

For a seamless extraction process, please ensure your documents are in one of our supported formats. Check our Supported File Types page for a list of all formats we currently accept and additional details to prepare your files accordingly.

Code Example

Note for PHP Users: Currently, the /uploadFiles endpoint supports uploading only one file per request. Please ensure you submit individual requests for each file you need to upload.

JavaScript

const fs = require('fs');
const axios = require('axios');
const FormData = require('form-data');

/**
 * Uploads files to the Extracta API using Axios for making HTTP requests.
 * 
 * @param {string} token - The authorization token to access the API.
 * @param {string} extractionId - The ID of the extraction process to which these files belong.
 * @param {Array.<string>} files - Paths to the files to be uploaded.
 * @param {string} [batchId=null] - Optional batch ID if the files belong to a specific batch.
 * @returns {Promise<Object>} The promise that resolves to the API response.
 */
async function uploadFiles(token, extractionId, files, batchId = null) {
    const url = "https://api.extracta.ai/api/v1/uploadFiles";
    let formData = new FormData();

    formData.append('extractionId', extractionId);
    if (batchId) {
        formData.append('batchId', batchId);
    }

    // Append files to formData
    files.forEach(file => {
        formData.append('files', fs.createReadStream(file));
    });

    try {
        const response = await axios.post(url, formData, {
            headers: {
                ...formData.getHeaders(),
                'Authorization': `Bearer ${token}`
            },
            // Axios automatically sets the Content-Type to multipart/form-data with the boundary.
        });

        // Handling response
        return response.data; // Directly return the parsed JSON response
    } catch (error) {
        // Handling errors
        throw error.response ? error.response.data : new Error('An unknown error occurred');
    }
}

async function main() {
    const token = 'apiKey';
    const extractionId = 'extractionId';
    const files = ['test_1.png', 'test_2.png'];

    try {
        const response = await uploadFiles(token, extractionId, files);
        console.log(response);
    } catch (error) {
        console.error("Failed to upload files:", error);
    }
}

main();

Python

import requests

def upload_files(token, extraction_id, files, batch_id=None):
    url = "https://api.extracta.ai/api/v1/uploadFiles"
    headers = {"Authorization": f"Bearer {token}"}

    # Prepare the files for uploading
    file_streams = [
        (
            "files",
            (
                file,
                open(file, "rb"),
                mimetypes.guess_type(file)[0] or "application/octet-stream",
            ),
        )
        for file in files
    ]
    payload = {"extractionId": extraction_id}
    if batch_id is not None:
        payload["batchId"] = batch_id

    try:
        response = requests.post(url, files=file_streams, data=payload, headers=headers)
        response.raise_for_status()  # This will raise an error for HTTP codes 400 or 500
        return response.json()  # Returns the JSON response if no error
    except requests.HTTPError as e:
        # Print server-side error message
        if response.status_code >= 400:
            error_message = response.json()
            print(f"Server returned an error: {error_message}")
        else:
            print(f"HTTP error occurred: {e}")
    except requests.RequestException as e:
        # Handle other requests exceptions
        print(f"Failed to upload files: {e}")
    except Exception as e:
        # Handle other possible exceptions
        print(f"An unexpected error occurred: {e}")
    return None

# Example usage
if __name__ == "__main__":
    token = 'apiKey'
    extraction_id = 'extractionId'
    files = ['test_1.png', 'test_2.png']

    try:
        response = upload_files(token, extraction_id, files)
        print(response)
    except Exception as e:
        print(f"Failed to upload files: {e}")

PHP

<?php

/**
 * Uploads files to the Extracta API using cURL for making HTTP requests.
 * 
 * @param string $token The authorization token to access the API.
 * @param string $extractionId The ID of the extraction process to which these files belong.
 * @param string $filePath Path to the file to be uploaded.
 * @param string|null $batchId Optional batch ID if the file belongs to a specific batch.
 * @return mixed The response from the API or an error message.
 */
function uploadFiles($token, $extractionId, $filePath, $batchId = null) {
    $url = 'https://api.extracta.ai/api/v1/uploadFiles';

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

    // Prepare the payload
    $payload = [
        'extractionId' => $extractionId,
        'files' => new CURLFile($filePath, 'image/jpeg', basename($filePath))
    ];

    if ($batchId !== null) {
        $payload['batchId'] = $batchId;
    }

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

    try {
        // Execute cURL session
        $response = curl_exec($ch);

        // Check for cURL errors
        if (curl_errno($ch)) {
            throw new Exception('Curl error: ' . curl_error($ch));
        }

        // Here, you could additionally parse the $response if it's in JSON format or if needed,
        // For simplicity, just returning the raw response for now
        return $response;
    } catch (Exception $e) {
        // Handle exceptions or errors here
        return 'Error: ' . $e->getMessage();
    } finally {
        // Always close the cURL session
        curl_close($ch);
    }
}

// Example usage
$token = 'apiKey';
$extractionId = 'extractiodId';
$filePath = './test_1.png';
$batchId = null;

try {
    $response = uploadFiles($token, $extractionId, $filePath, $batchId);
    echo $response;
} catch (Exception $e) {
    echo "Failed to upload file: " . $e->getMessage();
}

?>

Responses

200

{
    "status": "uploaded",
    "extractionId": "extractionId",
    "batchId": "batchId",
    "files": [
        {
            "fileId": "fileId",
            "fileName": "fileName",
            "numberOfPages": 1,
            "url": "url"
        }
    ]
}

400

{
    "status": "error",
    "message": "Extraction does not exist",
    "extractionId": "extractionId"
}

500

{
    "status": "error",
    "message": "Error uploading files"
}