Suparse API Specification

Suparse Document Processing API

Base URLs:

https://api.suparse.com

Email: Support

Authentication

HTTP Authentication, scheme: bearer

API Key (APIKeyHeader)
- Parameter Name: X-API-Key, in: header.

Documents

Upload, process, and manage financial documents (invoices, receipts, bank statements, and more).

Create document upload URL

POST /api/v1/documents/upload-url

Initiate a two-step document upload by validating file metadata, generating a presigned storage URL, and returning the upload reference ID.

Body parameter

{
  "filename": "string",
  "content_type": "string",
  "size": 0
}

Parameters

Name	In	Type	Required	Description
body	body	UploadUrlRequest	true	none

Example responses

200 Response

{
  "upload_url": "string",
  "upload_reference_id": "string",
  "expires_in": 0
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	UploadUrlResponse
400	Bad Request	Invalid file type or file size	ErrorDetail
401	Unauthorized	Not authenticated	ErrorDetail
422	Unprocessable Entity	Validation Error	HTTPValidationError
500	Internal Server Error	Failed to generate upload URL	ErrorDetail

Direct-to-Storage Document Uploads

Upload Flow

Call the backend to create a presigned upload URL.
Upload the file bytes directly to the returned upload_url with PUT.
Call the backend to confirm the upload and start document processing.

1. Create an Upload URL

POST /api/v1/documents/upload-url
Authorization: Bearer <token>
Content-Type: application/json

API keys are also supported with X-API-Key.

Request body:

{
  "filename": "invoice.pdf",
  "content_type": "application/pdf",
  "size": 123456
}

Fields:

Field	Type	Required	Notes
`filename`	string	yes	Original filename. The backend uses the extension when creating the storage key.
`content_type`	string	yes	Must be one of the supported MIME types.
`size`	integer	yes	File size in bytes. Must be greater than `0` and no more than `20MB`.

Supported MIME types:

MIME type	File type
`application/pdf`	PDF
`image/jpeg`	JPEG
`image/png`	PNG
`image/heic`	HEIC
`image/heif`	HEIF

Example response:

{
  "upload_url": "https://<storage-endpoint>/<bucket>/<signed-object-key>?...",
  "upload_reference_id": "c4e6.../upload/2026/5/7b4d....pdf",
  "expires_in": 900
}

Response fields:

Field	Type	Notes
`upload_url`	string	Presigned storage URL. Upload the file to this URL with `PUT`.
`upload_reference_id`	string	Storage object path. Send this unchanged to `confirm-upload`.
`expires_in`	integer	URL lifetime in seconds. Current value is `900` seconds.

2. Upload the File to Object Storage

Use PUT against the returned upload_url.

The upload request is made to the external storage URL, not to the Suparse API domain. Do not include the Suparse bearer token or API key on this request. The signature embedded in the URL authorizes the upload.

PUT <upload_url>
Content-Type: application/pdf
Content-Length: 123456
 
<raw file bytes>

The Content-Type must match the content_type value sent to POST /api/v1/documents/upload-url.

The uploaded body must be the same file bytes whose size was sent as size. Browser APIs usually set Content-Length automatically. If using an HTTP client that lets you set it manually, set it to the same byte size.

cURL Example

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary "@invoice.pdf"

Expected success response from S3-compatible storage is usually 200 OK. Some providers may return another 2xx status. Treat any 2xx response as a successful storage upload.

Common failure causes:

Status	Likely cause
`403 Forbidden`	URL expired, signature mismatch, wrong `Content-Type`, or modified URL.
`400 Bad Request`	Invalid signed headers or request shape.

3. Confirm the Upload

After the storage PUT succeeds, call the backend:

POST /api/v1/documents/confirm-upload
Authorization: Bearer <token>
Content-Type: application/json

Request body:

{
  "upload_reference_id": "c4e6.../upload/2026/5/7b4d....pdf",
  "filename": "invoice.pdf",
  "template_id": null,
  "split": false,
  "auto_approve": false
}

Fields:

Field	Type	Required	Notes
`upload_reference_id`	string	yes	Use the exact value returned by `upload-url`.
`filename`	string	yes	Original filename to display and store in document metadata.
`template_id`	UUID or null	no	Optional extraction template.
`split`	boolean	no	Whether to run targeted splitting when a template is provided.
`auto_approve`	boolean	no	Whether eligible processing should be auto-approved.

Example success response:

{
  "task_id": "8b2e6f56-5f5f-4f52-8f8a-07e4628a5a08",
  "document_id": "8b2e6f56-5f5f-4f52-8f8a-07e4628a5a08",
  "status": "processing"
}

The backend verifies that the object exists in storage, samples the first bytes to validate the actual file type, checks credits and template access, creates the document record, and enqueues processing.

Important Client Rules

Use PUT for upload_url.
Upload raw file bytes, not multipart/form-data.
Send the same Content-Type used when creating the upload URL.
Complete the storage upload before calling confirm-upload.
Preserve upload_reference_id exactly as returned.
Do not send Suparse authorization headers to the external storage URL.
Retry by requesting a new upload_url if the URL expires.

Confirm document upload

POST /api/v1/documents/confirm-upload

Confirm a completed storage upload, validate uploaded content, check credits, create the document record, enqueue processing, and return the parent document ID as task_id for polling with GET /api/v1/tasks/{task_id}.

Body parameter

{
  "upload_reference_id": "string",
  "filename": "string",
  "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  "split": false,
  "auto_approve": false
}

Parameters

Name	In	Type	Required	Description
body	body	ConfirmUploadRequest	true	none

Example responses

202 Response

{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  "status": "processing"
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Successful Response	ConfirmUploadResponse
400	Bad Request	Invalid file content or user team state	ErrorDetail
401	Unauthorized	Not authenticated	ErrorDetail
403	Forbidden	Insufficient credits or invalid template	ErrorDetail
404	Not Found	Uploaded file not found	ErrorDetail
422	Unprocessable Entity	Validation Error	HTTPValidationError
500	Internal Server Error	Failed to validate upload	ErrorDetail

Bulk delete documents

DELETE /api/v1/documents/

Soft-delete one or more accessible documents, cascade deletion to descendants, deactivate storage records, and delete physical files from storage best-effort.

Body parameter

{
  "document_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	DocumentBulkDelete	true	none

Example responses

401 Response

{
  "detail": "string"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Successful Response	None
401	Unauthorized	Not authenticated	ErrorDetail
403	Forbidden	User has no team or cannot delete requested documents	ErrorDetail
404	Not Found	No accessible documents found	ErrorDetail
422	Unprocessable Entity	Validation Error	HTTPValidationError

Get document extraction JSON

GET /api/v1/documents/{document_id}

Return the structured extraction JSON for one processed document. This is the single-document convenience equivalent of POST /api/v1/exports/documents?format=json with a body containing this document ID. The document must belong to the authenticated user's team, must be accessible, and must have a processing result.

Parameters

Name	In	Type	Required	Description
document_id	path	string(uuid)	true	none

Example responses

200 Response

{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "original_file": "string",
  "total_documents_extracted": 0,
  "documents": [
    {
      "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
      "file_name": "string",
      "page_start": 0,
      "page_end": 0,
      "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
      "credits_used": 0,
      "extracted_data": {}
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	DocumentExtractionResponse
400	Bad Request	User is not part of a team	ErrorDetail
401	Unauthorized	Not authenticated	ErrorDetail
404	Not Found	Document not found, access denied, or no extraction result exists	ErrorDetail
422	Unprocessable Entity	Validation Error	HTTPValidationError
500	Internal Server Error	Database error occurred	ErrorDetail

Templates

Create and manage custom document parsing templates for repeatable extraction workflows.

List templates

GET /api/v1/templates

List active system templates and active templates belonging to the authenticated user's team with explicit team filtering.

Example responses

200 Response

[
  {
    "name": "string",
    "description": "stringst",
    "template_language": "str",
    "schema_definition": {
      "general_part": {
        "property1": {
          "name": "string",
          "prompt": "string",
          "field_type": "general",
          "format_type": "text",
          "format_options": [
            "string"
          ],
          "position": 0,
          "char_limit": 15000,
          "is_editable": true,
          "is_displayed": true,
          "qbo_mapping": "string"
        },
        "property2": {
          "name": "string",
          "prompt": "string",
          "field_type": "general",
          "format_type": "text",
          "format_options": [
            "string"
          ],
          "position": 0,
          "char_limit": 15000,
          "is_editable": true,
          "is_displayed": true,
          "qbo_mapping": "string"
        }
      },
      "table_part": {
        "property1": {
          "name": "string",
          "prompt": "string",
          "field_type": "general",
          "format_type": "text",
          "format_options": [
            "string"
          ],
          "position": 0,
          "char_limit": 15000,
          "is_editable": true,
          "is_displayed": true,
          "qbo_mapping": "string"
        },
        "property2": {
          "name": "string",
          "prompt": "string",
          "field_type": "general",
          "format_type": "text",
          "format_options": [
            "string"
          ],
          "position": 0,
          "char_limit": 15000,
          "is_editable": true,
          "is_displayed": true,
          "qbo_mapping": "string"
        }
      }
    },
    "prompt_set": {
      "global_instructions": "string",
      "general_prompt": "string",
      "table_prompt": "string"
    },
    "validation_rules": {
      "rules": [
        {
          "rule_name": "string",
          "rule_type": "required",
          "targets": [
            "string"
          ],
          "config": {
            "set_1": [
              "string"
            ],
            "set_2": [
              "string"
            ],
            "tolerance": 0,
            "alternatives": [
              {
                "set_2": [
                  "string"
                ],
                "label": "string"
              }
            ]
          }
        }
      ]
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "template_group_id": "d11c98e2-fc64-4f02-9eed-d318de7100fa",
    "parent_template_id": "f3fd427a-ba48-458c-bcf9-3018d926ddce",
    "version": 0,
    "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
    "is_active": true,
    "is_system_template": true,
    "created_at": "2019-08-24T14:15:22Z",
    "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	Inline
401	Unauthorized	Not authenticated	ErrorDetail
500	Internal Server Error	Failed to retrieve templates	ErrorDetail

Response Schema

Status Code 200

Response List Templates Api V1 Templates Get

Field	Type	Required	Description
Response List Templates Api V1 Templates Get	ExtractionTemplateRead[]	no
-ExtractionTemplateRead	ExtractionTemplateRead	no
--name	string	yes	Template name
--description	string \| null	no	Short description
--template_language	string	yes
--schema_definition	SchemaDefinition	yes	The complete, validatable schema definition for an extraction template.
---general_part	object	no	Dictionary of general fields.
----FieldMetadata	FieldMetadata	no	Defines the validated structure for the metadata of a single user-defined field.
-----name	string	yes	User-facing display name.
-----prompt	string \| null	no	Specific prompt instructions for this field.
-----field_type	string	yes
-----format_type	string	yes
-----format_options	string[] \| null	no	Choices for 'multiple_choice' type.
-----position	integer	yes	The display order in the UI.
-----char_limit	integer	no	Character limit for the field description.
-----is_editable	boolean	no	Controls if the value can be manually corrected.
-----is_displayed	boolean	no	Controls UI visibility of this field.
-----qbo_mapping	string \| null	no	Semantic tag for QuickBooks mapping.
---table_part	object \| null	no	Dictionary of table columns.
-----FieldMetadata	FieldMetadata	no	Defines the validated structure for the metadata of a single user-defined field.
--prompt_set	PromptSet	yes	Contains the prompt templates for general and table extraction.
---global_instructions	string \| null	no	Optional instructions prepended to all prompts.
---general_prompt	string	yes	Main prompt for general data extraction.
---table_prompt	string	yes	Prompt for extracting table rows.
--validation_rules	ValidationRules	yes
---rules	ValidationRule[]	no
----ValidationRule	ValidationRule	no
-----rule_name	string	yes	User-friendly name for the validation rule.
-----rule_type	string	yes
-----targets	string[]	no	List of field paths (e.g., 'general_part.invoice_date').
-----config	ValidationRuleConfig	no	Configuration parameters for validation rules.
------set_1	string[] \| null	no	List of field paths for LHS of equation (compare_totals).
------set_2	string[] \| null	no	List of field paths for RHS of equation (compare_totals).
------tolerance	number \| string \| null	no	Allowed difference for float comparison.
------alternatives	ComparisonAlternative[] \| null	no	Alternative comparisons to try if primary fails. Passes if ANY succeeds.
--------ComparisonAlternative	ComparisonAlternative	no	A single alternative comparison for OR logic in compare_totals.
---------set_2	string[]	yes	Alternative set_2 field paths to try if primary comparison fails.
---------label	string \| null	no	Optional label for this alternative (e.g., 'vs subtotal').
--id	string(uuid)	yes
--template_group_id	string(uuid)	yes
--parent_template_id	string(uuid) \| null	yes
--version	integer	yes
--team_id	string(uuid) \| null	yes
--is_active	boolean	yes
--is_system_template	boolean	yes
--created_at	string(date-time)	yes
--created_by_user_id	string(uuid)	yes

Enumerated Values

Property	Value
field_type	general
field_type	table
format_type	text
format_type	number
format_type	date
format_type	boolean
format_type	multiple_choice
rule_type	required
rule_type	compare_totals

Exports

Export extracted data as CSV, Excel, or Google Sheets.

Export documents

POST /api/v1/exports/documents

Export processed data for one or more documents in the chosen format. Supports original mode (each document with its processing template) and unified mode (groups by template group, projecting all data onto the latest active template schema). For json, csv, and xlsx, the response body is the generated export file returned directly from this request with a Content-Disposition attachment filename. If the export produces multiple files, the response is a ZIP archive. For google_sheets, the response is JSON containing the created spreadsheet URL(s) or Drive folder URL.

Body parameter

{
  "document_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Parameters

Name	In	Type	Required	Description
format	query	ExportFormat	true	Download format: json, csv, xlsx, or google_sheets
export_type	query	ExportType	false	Export type: 'original' for full data, 'unified' for standardized data.
body	body	DownloadRequest	true	none

Enumerated Values

Parameter	Value
format	json
format	csv
format	xlsx
format	quickbooks_csv
format	google_sheets
export_type	original
export_type	unified

Example responses

200 Response

[
  {}
]

Responses

Status	Meaning	Description	Schema
200	OK	Export file bytes for json/csv/xlsx formats, a ZIP archive when multiple files are generated, or a JSON object with Google Sheets URL(s) for format=google_sheets.	string
401	Unauthorized	Not authenticated	ErrorDetail
404	Not Found	No accessible documents found for the given IDs	ErrorDetail
422	Unprocessable Entity	Validation Error	HTTPValidationError
500	Internal Server Error	Failed to generate export files	ErrorDetail

Response Headers

Status	Header	Type	Format	Description
200	Content-Disposition	string		Attachment filename for direct file downloads.

Tasks

Check the status of background document processing tasks.

Get task status

GET /api/v1/tasks/{task_id}

Get the aggregated status of a document processing task. The task_id is the document_id of the parent document from the initial upload. Designed to be polled by clients to track progress from classification through completion.

Parameters

Name	In	Type	Required	Description
task_id	path	string(uuid)	true	none

Example responses

200 Response

{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "overall_status": "uploading",
  "created_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "error_message": "string",
  "sub_documents": [],
  "internal_details": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	TaskStatusResponse
401	Unauthorized	Not authenticated	ErrorDetail
404	Not Found	Task not found	ErrorDetail
422	Unprocessable Entity	Validation Error	HTTPValidationError
500	Internal Server Error	Internal server error	ErrorDetail

Schemas

ComparisonAlternative

{
  "set_2": [
    "string"
  ],
  "label": "string"
}

Properties

Field	Type	Required	Description
set_2	string[]	yes	Alternative set_2 field paths to try if primary comparison fails.
label	string \| null	no	Optional label for this alternative (e.g., 'vs subtotal').

ConfirmUploadRequest

{
  "upload_reference_id": "string",
  "filename": "string",
  "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  "split": false,
  "auto_approve": false
}

Properties

Field	Type	Required
upload_reference_id	string	yes
filename	string	yes
template_id	string(uuid) \| null	no
split	boolean	no
auto_approve	boolean	no

ConfirmUploadResponse

{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  "status": "processing"
}

Properties

Field	Type	Required	Description
task_id	string(uuid)	yes	ID to poll via GET /api/v1/tasks/{task_id}. This is the parent document_id.
document_id	string(uuid)	yes	Parent document ID created for the upload. Same value as task_id.
status	string	yes

DocumentBulkDelete

{
  "document_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Properties

Field	Type	Required	Description
document_ids	string[]	yes

DocumentExtractionItem

{
  "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  "file_name": "string",
  "page_start": 0,
  "page_end": 0,
  "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  "credits_used": 0,
  "extracted_data": {}
}

Properties

Field	Type	Required	Description
document_id	string(uuid)	yes	Document ID that produced this extraction result.
file_name	string	yes	Stored document filename.
page_start	integer	yes	One-based start page for this extracted document.
page_end	integer	yes	One-based end page for this extracted document.
template_id	string(uuid) \| null	yes	Template used to process the document.
credits_used	integer	yes	Credits consumed by this document, currently equal to page count.
extracted_data	object	yes	Structured extraction result for the document.

DocumentExtractionResponse

{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "original_file": "string",
  "total_documents_extracted": 0,
  "documents": [
    {
      "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
      "file_name": "string",
      "page_start": 0,
      "page_end": 0,
      "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
      "credits_used": 0,
      "extracted_data": {}
    }
  ]
}

Properties

Field	Type	Required	Description
task_id	string(uuid)	yes	Parent task/document ID. For standalone documents this is the requested document ID.
original_file	string	yes	Original parent upload filename.
total_documents_extracted	integer	yes	Number of extracted documents included in this response.
documents	DocumentExtractionItem[]	yes	Extraction result entries. This endpoint returns entries for the requested document only.

DownloadRequest

{
  "document_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Properties

Field	Type	Required	Description
document_ids	string[]	yes

ErrorDetail

{
  "detail": "string"
}

Properties

Field	Type	Required	Description
detail	string	yes

ExportFormat

"json"

Properties

Field	Type	Required	Description
ExportFormat	string	no

Enumerated Values

Property	Value
ExportFormat	json
ExportFormat	csv
ExportFormat	xlsx
ExportFormat	quickbooks_csv
ExportFormat	google_sheets

ExportType

"original"

Properties

Field	Type	Required	Description
ExportType	string	no

Enumerated Values

Property	Value
ExportType	original
ExportType	unified

ExtractionTemplateRead

{
  "name": "string",
  "description": "stringst",
  "template_language": "str",
  "schema_definition": {
    "general_part": {
      "property1": {
        "name": "string",
        "prompt": "string",
        "field_type": "general",
        "format_type": "text",
        "format_options": [
          "string"
        ],
        "position": 0,
        "char_limit": 15000,
        "is_editable": true,
        "is_displayed": true,
        "qbo_mapping": "string"
      },
      "property2": {
        "name": "string",
        "prompt": "string",
        "field_type": "general",
        "format_type": "text",
        "format_options": [
          "string"
        ],
        "position": 0,
        "char_limit": 15000,
        "is_editable": true,
        "is_displayed": true,
        "qbo_mapping": "string"
      }
    },
    "table_part": {
      "property1": {
        "name": "string",
        "prompt": "string",
        "field_type": "general",
        "format_type": "text",
        "format_options": [
          "string"
        ],
        "position": 0,
        "char_limit": 15000,
        "is_editable": true,
        "is_displayed": true,
        "qbo_mapping": "string"
      },
      "property2": {
        "name": "string",
        "prompt": "string",
        "field_type": "general",
        "format_type": "text",
        "format_options": [
          "string"
        ],
        "position": 0,
        "char_limit": 15000,
        "is_editable": true,
        "is_displayed": true,
        "qbo_mapping": "string"
      }
    }
  },
  "prompt_set": {
    "global_instructions": "string",
    "general_prompt": "string",
    "table_prompt": "string"
  },
  "validation_rules": {
    "rules": [
      {
        "rule_name": "string",
        "rule_type": "required",
        "targets": [
          "string"
        ],
        "config": {
          "set_1": [
            "string"
          ],
          "set_2": [
            "string"
          ],
          "tolerance": 0,
          "alternatives": [
            {
              "set_2": [
                "string"
              ],
              "label": "string"
            }
          ]
        }
      }
    ]
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "template_group_id": "d11c98e2-fc64-4f02-9eed-d318de7100fa",
  "parent_template_id": "f3fd427a-ba48-458c-bcf9-3018d926ddce",
  "version": 0,
  "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
  "is_active": true,
  "is_system_template": true,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473"
}

Properties

Field	Type	Required	Description
name	string	yes	Template name
description	string \| null	no	Short description
template_language	string	yes
schema_definition	SchemaDefinition	yes	The complete, validatable schema definition for an extraction template.
prompt_set	PromptSet	yes	Contains the prompt templates for general and table extraction.
validation_rules	ValidationRules	yes
id	string(uuid)	yes
template_group_id	string(uuid)	yes
parent_template_id	string(uuid) \| null	yes
version	integer	yes
team_id	string(uuid) \| null	yes
is_active	boolean	yes
is_system_template	boolean	yes
created_at	string(date-time)	yes
created_by_user_id	string(uuid)	yes

FieldMetadata

{
  "name": "string",
  "prompt": "string",
  "field_type": "general",
  "format_type": "text",
  "format_options": [
    "string"
  ],
  "position": 0,
  "char_limit": 15000,
  "is_editable": true,
  "is_displayed": true,
  "qbo_mapping": "string"
}

Properties

Field	Type	Required	Description
name	string	yes	User-facing display name.
prompt	string \| null	no	Specific prompt instructions for this field.
field_type	string	yes
format_type	string	yes
format_options	string[] \| null	no	Choices for 'multiple_choice' type.
position	integer	yes	The display order in the UI.
char_limit	integer	no	Character limit for the field description.
is_editable	boolean	no	Controls if the value can be manually corrected.
is_displayed	boolean	no	Controls UI visibility of this field.
qbo_mapping	string \| null	no	Semantic tag for QuickBooks mapping.

Enumerated Values

Property	Value
field_type	general
field_type	table
format_type	text
format_type	number
format_type	date
format_type	boolean
format_type	multiple_choice

HTTPValidationError

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Properties

Field	Type	Required	Description
detail	ValidationError[]	no

OverallTaskStatus

"uploading"

Properties

Field	Type	Required	Description
OverallTaskStatus	string	no

Enumerated Values

Property	Value
OverallTaskStatus	uploading
OverallTaskStatus	classifying
OverallTaskStatus	awaiting_approval
OverallTaskStatus	processing
OverallTaskStatus	partially_completed
OverallTaskStatus	completed
OverallTaskStatus	failed
OverallTaskStatus	insufficient_credits

PromptSet

{
  "global_instructions": "string",
  "general_prompt": "string",
  "table_prompt": "string"
}

Properties

Field	Type	Required	Description
global_instructions	string \| null	no	Optional instructions prepended to all prompts.
general_prompt	string	yes	Main prompt for general data extraction.
table_prompt	string	yes	Prompt for extracting table rows.

SchemaDefinition

{
  "general_part": {
    "property1": {
      "name": "string",
      "prompt": "string",
      "field_type": "general",
      "format_type": "text",
      "format_options": [
        "string"
      ],
      "position": 0,
      "char_limit": 15000,
      "is_editable": true,
      "is_displayed": true,
      "qbo_mapping": "string"
    },
    "property2": {
      "name": "string",
      "prompt": "string",
      "field_type": "general",
      "format_type": "text",
      "format_options": [
        "string"
      ],
      "position": 0,
      "char_limit": 15000,
      "is_editable": true,
      "is_displayed": true,
      "qbo_mapping": "string"
    }
  },
  "table_part": {
    "property1": {
      "name": "string",
      "prompt": "string",
      "field_type": "general",
      "format_type": "text",
      "format_options": [
        "string"
      ],
      "position": 0,
      "char_limit": 15000,
      "is_editable": true,
      "is_displayed": true,
      "qbo_mapping": "string"
    },
    "property2": {
      "name": "string",
      "prompt": "string",
      "field_type": "general",
      "format_type": "text",
      "format_options": [
        "string"
      ],
      "position": 0,
      "char_limit": 15000,
      "is_editable": true,
      "is_displayed": true,
      "qbo_mapping": "string"
    }
  }
}

Properties

Field	Type	Required	Description
general_part	object	no	Dictionary of general fields.
-additionalProperties	FieldMetadata	no	Defines the validated structure for the metadata of a single user-defined field.
table_part	object \| null	no	Dictionary of table columns.
--additionalProperties	FieldMetadata	no	Defines the validated structure for the metadata of a single user-defined field.

SubDocumentStatus

{
  "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  "status": "string",
  "assigned_template_name": "string"
}

Properties

Field	Type	Required
document_id	string(uuid)	yes
status	string	yes
assigned_template_name	string \| null	no

TaskStatusResponse

{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "overall_status": "uploading",
  "created_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "error_message": "string",
  "sub_documents": [],
  "internal_details": {}
}

Properties

Field	Type	Required
task_id	string(uuid)	yes
overall_status	OverallTaskStatus	yes
created_at	string(date-time)	yes
completed_at	string(date-time) \| null	no
error_message	string \| null	no
sub_documents	SubDocumentStatus[]	no
internal_details	object \| null	no

UploadUrlRequest

{
  "filename": "string",
  "content_type": "string",
  "size": 0
}

Properties

Field	Type	Required	Description
filename	string	yes
content_type	string	yes
size	integer	yes	File size in bytes.

UploadUrlResponse

{
  "upload_url": "string",
  "upload_reference_id": "string",
  "expires_in": 0
}

Properties

Field	Type	Required
upload_url	string	yes
upload_reference_id	string	yes
expires_in	integer	yes

ValidationError

{
  "loc": [
    "string"
  ],
  "msg": "string",
  "type": "string",
  "input": null,
  "ctx": {}
}

Properties

Field	Type	Required
loc	string \| integer	yes
msg	string	yes
type	string	yes
input	any	no
ctx	object	no

ValidationRule

{
  "rule_name": "string",
  "rule_type": "required",
  "targets": [
    "string"
  ],
  "config": {
    "set_1": [
      "string"
    ],
    "set_2": [
      "string"
    ],
    "tolerance": 0,
    "alternatives": [
      {
        "set_2": [
          "string"
        ],
        "label": "string"
      }
    ]
  }
}

Properties

Field	Type	Required	Description
rule_name	string	yes	User-friendly name for the validation rule.
rule_type	string	yes
targets	string[]	no	List of field paths (e.g., 'general_part.invoice_date').
config	ValidationRuleConfig	no	Rule-specific configuration parameters.

Enumerated Values

Property	Value
rule_type	required
rule_type	compare_totals

ValidationRuleConfig

{
  "set_1": [
    "string"
  ],
  "set_2": [
    "string"
  ],
  "tolerance": 0,
  "alternatives": [
    {
      "set_2": [
        "string"
      ],
      "label": "string"
    }
  ]
}

Properties

Field	Type	Required	Description
set_1	string[] \| null	no	List of field paths for LHS of equation (compare_totals).
set_2	string[] \| null	no	List of field paths for RHS of equation (compare_totals).
tolerance	number \| string \| null	no	Allowed difference for float comparison.
alternatives	ComparisonAlternative[] \| null	no	Alternative comparisons to try if primary fails. Passes if ANY succeeds.

ValidationRules

{
  "rules": [
    {
      "rule_name": "string",
      "rule_type": "required",
      "targets": [
        "string"
      ],
      "config": {
        "set_1": [
          "string"
        ],
        "set_2": [
          "string"
        ],
        "tolerance": 0,
        "alternatives": [
          {
            "set_2": [
              "string"
            ],
            "label": "string"
          }
        ]
      }
    }
  ]
}

Properties

Field	Type	Required	Description
rules	ValidationRule[]	no