Processing Documents

FSCO provides APIs for creating and uploading documents. The typical workflow for processing documents is:

1. Create a document record using the API
2. Upload the document file
3. Receive webhook notifications as the document is processed

1. Create Document

   When you create a document, FSCO will:

   • Generate a unique document ID
   • Associate it with your specified template and collection
   • Return the document ID immediately
   • Return a webhook notification when the document is created

2. Upload Document File

   After uploading a file, FSCO will:

   • Validate and scan the file
   • Process it using the template’s AI model and prompts
   • Extract the requested data
   • Send webhook notifications at each stage

Webhook Events

The following webhook events are sent during document processing:

• document.created - Sent when the document record is created
• document.updated - Sent when the document record was updated
• ocr.started - Sent when document text extraction started
• ocr.completed - Sent when document text extraction is completed
• ocr.failed - Sent when the document text could not be extracted
• ai.started - Sent when AI processing begins
• ai.typeSelected - Sent when the document type is determined by the AI processor
• ai.processed - Sent when AI processing is completed
• ai.failed - Sent when the AI processing failed

Each webhook includes the document ID and current status, allowing you to track the document’s progress through your system.

On receipt of a webhook failure event, you can retrieve the document activity using the Get Document Activity endpoint.

This guide covers both creating new documents and uploading existing document files.

Prerequisites

Before you begin, ensure you have:

• A valid FSCO API key
• Your application’s environment configured with the API key
• A template ID for document processing
• A collection ID for organizing documents

Create a Document

Endpoint

POST /v2/document

Request Parameters

{
  "refId": "2a2e4823-017c-4acd-a683-87e91c647500",
  "docExt": "application/pdf",
  "docName": "figma_invoice_2025-05-06.pdf",
  "docType": "invoice",
  "isTest": false,
  "templateId": "38aff0fb-3df4-41f3-a266-3b85984f72b8",
  "source": "My API",
  "uploadBatchId": "2993F653-E268-4CE6-A6A0-A5FC05DB1888"
}

The request requires:

• templateId: The ID of the template to use for processing
• refId: The ID of the document in your system
• docExt: The extension of the document file
• docName: The name of the document file
• docType: The type of document (from the list of supported document types)
• isTest: Whether the document is a test
• source: The source of the document (e.g. “My API”)
• uploadBatchId: The ID of the upload

Example Request

cURL

create-document.sh

#!/bin/bash

curl -X POST "https://api.fsco.io/v2/document" \
  -H "x-api-key: $FSCO_API_KEY" \
  -H "x-api-secret: $FSCO_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "refId": "2a2e4823-017c-4acd-a683-87e91c647500",
    "docExt": "application/pdf",
    "docName": "figma_invoice_2025-05-06.pdf",
    "docType": "invoice",
    "isTest": false,
    "templateId": "8c1d496f-2827-4750-a11f-74b48c11108d",
    "collectionId": "9d2e507g-3938-5861-b22g-85c59d22219e",
    "source": "My API",
    "uploadBatchId": "2993F653-E268-4CE6-A6A0-A5FC05DB1888"
  }'

TypeScript

create-document.ts

import axios from 'axios';

const apiKey = process.env.FSCO_API_KEY;
const apiSecret = process.env.FSCO_API_SECRET;
const baseURL = 'https://api.fsco.com/v2';

async function createDocument() {
  try {
    const response = await axios.post(
      `${baseURL}/documents`,
      {
        docExt: 'application/pdf',
        docName: 'Your Document Name',
        docType: 'invoice',
        isTest: false,
        templateId: '8c1d496f-2827-4750-a11f-74b48c11108d',
        collectionId: '8c1d496f-2827-4750-a11f-74b48c11108d',
        refId: "2a2e4823-017c-4acd-a683-87e91c647500",
        source: "My API",
        uploadBatchId: "2993F653-E268-4CE6-A6A0-A5FC05DB1888"
      },
      {
        headers: {
          'x-api-key': apiKey,
          'x-api-secret': apiSecret,
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Document created:', response.data);
  } catch (error) {
    console.error('Error creating document:', error);
  }
}

// Example usage
createDocument();

Python

create-document.py

import os
import requests

# Get API credentials from environment variables
api_key = os.getenv("FSCO_API_KEY")
api_secret = os.getenv("FSCO_API_SECRET")

# Set up headers with API credentials

def create_document():
    url = 'https://api.fsco.io/v2/document'
    headers = {
    "x-api-key": api_key,
    "x-api-secret": api_secret,
    "Content-Type": "application/json"
    }

    # Prepare the request payload
    payload = {
        "refId": "2a2e4823-017c-4acd-a683-87e91c647500",
        "docExt": "application/pdf",
        "docName": "figma_invoice_2025-05-06.pdf",
        "docType": "invoice",
        "templateId": "YOUR_TEMPLATE_ID",
        "collectionId": "YOUR_COLLECTION_ID",
        "isTest": False,
        "source": "My API",
        "uploadBatchId": "2993F653-E268-4CE6-A6A0-A5FC05DB1888"
    }

    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        print('Document created:', response.json())
    except requests.exceptions.RequestException as e:
        print('Error creating document:', e)

# Example usage
create_document()

.NET

create-document.cs

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class DocumentCreator
{
    static async Task Main()
    {
        var apiKey = Environment.GetEnvironmentVariable("FSCO_API_KEY");
        var apiSecret = Environment.GetEnvironmentVariable("FSCO_API_SECRET");

        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", apiKey);
        client.DefaultRequestHeaders.Add("x-api-secret", apiSecret);
        client.DefaultRequestHeaders.Add("Content-Type", "application/json");

        var document = new
        {
            refId = "2a2e4823-017c-4acd-a683-87e91c647500",
            docExt = "application/pdf",
            docName = "figma_invoice_2025-05-06.pdf",
            docType = "invoice",
            isTest = false,
            templateId = "8c1d496f-2827-4750-a11f-74b48c11108d",
            collectionId = "8c1d496f-2827-4750-a11f-74b48c11108d",
            source = "My API",
            uploadBatchId = "2993F653-E268-4CE6-A6A0-A5FC05DB1888"
        };

        var content = new StringContent(
            JsonSerializer.Serialize(document),
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://api.fsco.io/v2/document", content);
        var responseString = await response.Content.ReadAsStringAsync();

        Console.WriteLine("Document created: " + responseString);
    }
}

Response

JSON

response.json

{
  "id": "bca4e809-3d44-4c27-9cda-89dc4471739b",
  "createdAt": "2025-05-20T00:12:45.011Z",
  "updatedAt": "2025-05-20T00:12:45.011Z",
  "isTest": false,
  "config": null,
  "fileData": null,
  "ocrProvider": "GOOGLE_DOCUMENT_AI",
  "ocrData": null,
  "docExt": "application/pdf",
  "docName": "my_invoice_2025-05-06.pdf",
  "docType": "invoice",
  "uploadBatchId": "4993F653-E268-4CE6-A6A0-A5FC05DB1888",
  "refId": "3a2e4823-017c-4acd-a683-87e91c647500",
  "blobId": "29a88889-e559-4d8b-8ab8-820090aace9b",
  "isPublic": false,
  "isUploaded": false,
  "source": "My API",
  "webhookId": null,
  "organisationId": "00b4b8e6-6e9c-4ec8-8bc0-4f27cba57e26",
  "userId": "0d05e804-cb6c-4bd4-8bf7-2d283b466eca",
  "status": "created",
  "version": 1,
  "prompts": [
      {
          "id": "91e0fd01-4df3-422b-afa7-adfd489cc0f5",
          "name": "Issuer",
          "format": "",
          "children": [],
          "itemType": "singleLine",
          "fieldType": "string",
          "description": "Who is the issuer of this invoice"
      }
  ],
  "providerModelId": "7b313983-7d8c-43ca-9714-c6767201bd3f",
  "documentGroups": [],
  "providerModel": {
      "providerModelId": "7b313983-7d8c-43ca-9714-c6767201bd3f",
      "providerName": "OPENAI",
      "modelName": "GPT_4O",
      "description": "Default provider model",
      "displayName": "GPT_4O"
  },
  "uploadUrl": "my-upload-url",
  "downloadUrl": "my-download-url"
}

Upload a Document File

Endpoint

PUT /v2/document/{documentId}

Request Parameters

The request requires a multipart form with:

• file: The document file to upload (PDF, DOCX, etc.)

Example Request

cURL

upload-document-file.sh

#!/bin/bash

curl -X PUT "https://api.fsco.io/v2/document/8c1d496f-2827-4750-a11f-74b48c11108d/file" \
  -H "x-api-key: $FSCO_API_KEY" \
  -H "x-api-secret: $FSCO_API_SECRET" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/your/document.pdf"

TypeScript

upload-document-file.ts

import axios from 'axios';
import * as fs from 'node:fs';
import FormData from 'form-data';

const apiKey = process.env.FSCO_API_KEY;
const apiSecret = process.env.FSCO_API_SECRET;
const baseURL = 'https://api.fsco.com/v2';

async function uploadDocumentFile() {
  try {
    const filePath = '/path/to/your/document.pdf';
    const fileBuffer = fs.readFileSync(filePath);

    const formData = new FormData();
    formData.append('file', fileBuffer, {
      filename: 'document.pdf',
      contentType: 'application/pdf'
    });

    const response = await axios.post(
      `${baseURL}/documents/8c1d496f-2827-4750-a11f-74b48c11108d/upload`,
      formData,
      {
        headers: {
          'x-api-key': apiKey,
          'x-api-secret': apiSecret,
          ...formData.getHeaders()
        }
      }
    );
    console.log('Document file uploaded:', response.data);
  } catch (error) {
    console.error('Error uploading document file:', error);
  }
}

// Example usage
uploadDocumentFile();

Python

upload-document-file.py

import os
import requests

api_key = os.getenv('FSCO_API_KEY')
api_secret = os.getenv('FSCO_API_SECRET')

def upload_document_file():
    document_id = '8c1d496f-2827-4750-a11f-74b48c11108d'
    file_path = '/path/to/your/document.pdf'
    url = f'https://api.fsco.io/v2/document/{document_id}/file'
    headers = {
        'x-api-key': api_key,
        'x-api-secret': api_secret,
        'Content-Type': 'multipart/form-data'
    }

    try:
        with open(file_path, 'rb') as file:
            files = {'file': file}
            response = requests.put(url, headers=headers, files=files)
            response.raise_for_status()
            print('Document file uploaded:', response.json())
    except requests.exceptions.RequestException as e:
        print('Error uploading document file:', e)

# Example usage
upload_document_file()

.NET

upload-document-file.cs

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class DocumentFileUploader
{
    static async Task Main()
    {
        var apiKey = Environment.GetEnvironmentVariable("FSCO_API_KEY");
        var apiSecret = Environment.GetEnvironmentVariable("FSCO_API_SECRET");

        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", apiKey);
        client.DefaultRequestHeaders.Add("x-api-secret", apiSecret);
        client.DefaultRequestHeaders.Add("Content-Type", "multipart/form-data");

        var documentId = "8c1d496f-2827-4750-a11f-74b48c11108d";
        var filePath = "/path/to/your/document.pdf";

        using var form = new MultipartFormDataContent();
        using var fileContent = new StreamContent(File.OpenRead(filePath));
        form.Add(fileContent, "file", Path.GetFileName(filePath));

        var response = await client.PutAsync($"https://api.fsco.io/v2/document/{documentId}/file", form);
        var responseString = await response.Content.ReadAsStringAsync();

        Console.WriteLine("Document file uploaded: " + responseString);
    }
}

Response

JSON

response.json

{
  "blobId": "29a88889-e559-4d8b-8ab8-820090aace91",
  "key": "the_generated_key_path",
  "public": false,
  "access": {
      "get": "the_generated_get_url",
      "put": "the_generated_put_url",
      "delete": "the_generated_delete_url"
  }
}

Important Notes

• Document files must be in a supported format (PDF, DOCX, etc.)
• The template ID must be valid and active
• The collection ID must exist in your organization
• Document processing is asynchronous and may take some time
• You can track document processing status through the document activity endpoint

Next Steps

• Viewing Documents
• Document Module Overview
• Document API Reference