{"openapi":"3.1.0","info":{"title":"Webhooks Reference","version":"1.0.0"},"paths":{},"webhooks":{"documentProcessing_receiveDocumentCreated":{"post":{"operationId":"documentProcessing_receiveDocumentCreated","summary":"Document Created","description":"Document created and webhook fired just before transitioning to `processing` status. Contains minimal information available at creation time.\n\n**⚠️ Important:** The document will be empty at this stage with status `processing`. API requests for this document will return a 202 Accepted status indicating the document is reserved but not yet available for retrieval. Full document data will be available after the `document.processed` event when status becomes `processed`.\n\nPlease refer to the latest documentation for payload details.\n","responses":{"200":{"description":"Webhook received successfully"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCreatedEvent"}}}}}},"documentProcessing_receiveDocumentProcessed":{"post":{"operationId":"documentProcessing_receiveDocumentProcessed","summary":"Document Processed","description":"Document processing complete with extracted data.\n\n**Payload Format:**\n- Data fields contain direct values (e.g., `{\"total\": 100}`)\n- Validation errors include `validation`, `info`, and `paths` fields\n- Document `type` field may contain built-in type name, custom type alias, or ObjectId for custom types\n- Timestamp uses Unix milliseconds format\n- The `url` field is typically an empty string (maintained for compatibility)\n","responses":{"200":{"description":"Webhook received successfully"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentProcessedEvent"}}}}}},"documentProcessing_receiveDocumentApproved":{"post":{"operationId":"documentProcessing_receiveDocumentApproved","summary":"Document Approved","description":"Document has been approved through workflow system.\n\n**⚠️ Note:** This event is currently being reevaluated and may change.\n\nPlease refer to the latest documentation for payload details.\n","responses":{"200":{"description":"Webhook received successfully"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentApprovedEvent"}}}}}},"documentProcessing_receiveDocumentDiscarded":{"post":{"operationId":"documentProcessing_receiveDocumentDiscarded","summary":"Document Discarded","description":"Document has been discarded through workflow system.\n\n**⚠️ Note:** This event is currently being reevaluated and may change.\n\nPlease refer to the latest documentation for payload details.\n","responses":{"200":{"description":"Webhook received successfully"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDiscardedEvent"}}}}}},"fileProcessing_receiveFileProcessed":{"post":{"operationId":"fileProcessing_receiveFileProcessed","summary":"File Processed","description":"File processing complete with generated document IDs","responses":{"200":{"description":"Webhook received successfully"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileProcessedEvent"}}}}}},"fileProcessing_receiveFileRejected":{"post":{"operationId":"fileProcessing_receiveFileRejected","summary":"File Rejected","description":"File rejected during processing with detailed error information","responses":{"200":{"description":"Webhook received successfully"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileRejectedEvent"}}}}}},"importProcessing_receiveImportProcessed":{"post":{"operationId":"importProcessing_receiveImportProcessed","summary":"Import Processed","description":"Batch import process complete with processing summary","responses":{"200":{"description":"Webhook received successfully"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportProcessedEvent"}}}}}}},"components":{"schemas":{"DocumentCreatedEventType":{"type":"string","enum":["document.created"],"description":"The type of event","title":"DocumentCreatedEventType"},"DocumentDataClientData":{"type":"object","properties":{},"description":"Custom metadata provided during upload","title":"DocumentDataClientData"},"DocumentDataPublicState":{"type":"string","enum":["processed","pendingCorrection","approved","discarded"],"description":"Document workflow state","title":"DocumentDataPublicState"},"DocumentDataConfidence":{"type":"string","enum":["low","medium","high"],"description":"Overall extraction confidence level for the document (\"low\", \"medium\", \"high\", or null)","title":"DocumentDataConfidence"},"DocumentDataValidationInfoErrorsItemsValidation":{"type":"string","enum":["required","pattern","length","compare","whitelist","amountsCoherence","totalsMismatch","linesMismatch","breakdownsMismatch","readingsMismatch","issuerRecipientNotEquals","checkEntity","sumsVsTotals","checkDuplicates","payslipTotalsMismatch","payslipSumsVsTotals","qrCode","custom","rates"],"description":"Validation rule identifier. Common values:\n- \"required\", \"pattern\", \"length\", \"compare\", \"whitelist\"\n- \"amountsCoherence\", \"totalsMismatch\", \"linesMismatch\"\n- \"checkDuplicates\", \"qrCode\", \"custom\", \"rates\"\n","title":"DocumentDataValidationInfoErrorsItemsValidation"},"DocumentDataValidationInfoErrorsItems":{"type":"object","properties":{"validation":{"$ref":"#/components/schemas/DocumentDataValidationInfoErrorsItemsValidation","description":"Validation rule identifier. Common values:\n- \"required\", \"pattern\", \"length\", \"compare\", \"whitelist\"\n- \"amountsCoherence\", \"totalsMismatch\", \"linesMismatch\"\n- \"checkDuplicates\", \"qrCode\", \"custom\", \"rates\"\n"},"info":{"type":"object","additionalProperties":{"description":"Any type"},"description":"Additional context about the validation error"},"paths":{"type":"array","items":{"type":"string"},"description":"JSON paths to affected fields (e.g., \"data.documentNumber\", \"data.lines[0].total\")"}},"title":"DocumentDataValidationInfoErrorsItems"},"DocumentDataValidationInfo":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/DocumentDataValidationInfoErrorsItems"},"description":"Array of validation errors. Each error includes:\n- `validation`: Rule that triggered (e.g., \"required\", \"pattern\", \"amountsCoherence\")\n- `info`: Additional context object\n- `paths`: JSON paths to affected fields (e.g., [\"data.documentNumber\"])\n"}},"description":"Validation results for the document","title":"DocumentDataValidationInfo"},"DocumentDataImportChannel":{"type":"string","enum":["email","upload","api"],"description":"Import channel used","title":"DocumentDataImportChannel"},"DocumentDataImportInfo":{"type":"object","properties":{},"description":"Additional import metadata (index, total, splitter info)","title":"DocumentDataImportInfo"},"DocumentDataImport":{"type":"object","properties":{"ref":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Unique identifier of the import batch"},"file":{"type":"string","description":"File identifier within the import"},"filename":{"type":"string","description":"Original filename during import"},"channel":{"$ref":"#/components/schemas/DocumentDataImportChannel","description":"Import channel used"},"info":{"$ref":"#/components/schemas/DocumentDataImportInfo","description":"Additional import metadata (index, total, splitter info)"}},"description":"Import metadata including file/import IDs, channel, and split information.\nEmpty object {} if not available.\n","title":"DocumentDataImport"},"DocumentData":{"type":"object","properties":{"_id":{"type":"string","description":"Unique document identifier"},"account":{"type":"string","description":"Account identifier"},"environment":{"type":"string","description":"Environment identifier"},"company":{"type":"string","description":"Company identifier"},"creator":{"type":"string","description":"User ID who created the document"},"clientData":{"$ref":"#/components/schemas/DocumentDataClientData","description":"Custom metadata provided during upload"},"type":{"type":"string","description":"Document type identifier. Can be a built-in type name (e.g., \"invoice\", \"ticket\"),\na custom type alias, or an ObjectId for custom types.\n"},"name":{"type":"string","description":"Document filename"},"isGroundTruth":{"type":"boolean","description":"Indicates the document is marked as Ground Truth (GT)"},"creation":{"type":"string","format":"date-time","description":"Document creation timestamp"},"images":{"type":"array","items":{"type":"string"},"description":"Array of image URLs (one per page)"},"original":{"type":"string","description":"URL to the original uploaded file"},"mimetype":{"type":"string","description":"MIME type of the document"},"data":{"type":"object","additionalProperties":{"description":"Any type"},"description":"Extracted field data from the document. Fields contain direct values (e.g., `{\"total\": 100}`).\nThe structure and available fields depend on the document type (invoice, ticket, etc.).\n"},"pageCount":{"type":"number","format":"double","description":"Number of pages in the document"},"publicState":{"$ref":"#/components/schemas/DocumentDataPublicState","description":"Document workflow state"},"confidence":{"oneOf":[{"$ref":"#/components/schemas/DocumentDataConfidence"},{"type":"null"}],"description":"Overall extraction confidence level for the document (\"low\", \"medium\", \"high\", or null)"},"validationInfo":{"$ref":"#/components/schemas/DocumentDataValidationInfo","description":"Validation results for the document"},"import":{"$ref":"#/components/schemas/DocumentDataImport","description":"Import metadata including file/import IDs, channel, and split information.\nEmpty object {} if not available.\n"}},"required":["_id","account","environment","company","name","creation","data","pageCount","publicState"],"description":"Document structure returned in webhooks and GET /documents/:id endpoint.\n\n**Data Format:**\n- Data fields contain direct values: `{\"total\": 100}`\n- Validation errors include `validation`, `info`, and `paths` fields\n- Document type can be a built-in type name, custom type alias, or ObjectId for custom types\n","title":"DocumentData"},"DocumentCreatedEventTimestamp":{"oneOf":[{"type":"number","format":"double"},{"type":"string","format":"date-time"}],"description":"Event timestamp","title":"DocumentCreatedEventTimestamp"},"DocumentCreatedEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/DocumentCreatedEventType","description":"The type of event"},"data":{"$ref":"#/components/schemas/DocumentData","description":"Event payload with document information"},"id":{"type":"string","description":"Unique identifier for this event (use for idempotent processing)"},"version":{"type":"string","description":"Version of the event schema"},"timestamp":{"$ref":"#/components/schemas/DocumentCreatedEventTimestamp","description":"Event timestamp"},"url":{"type":"string","description":"URL field (typically empty string for security)"}},"required":["type","data","id","version","timestamp"],"description":"Base event structure for document.* events","title":"DocumentCreatedEvent"},"DocumentProcessedEventType":{"type":"string","enum":["document.processed"],"description":"The type of event","title":"DocumentProcessedEventType"},"DocumentProcessedEventTimestamp":{"oneOf":[{"type":"number","format":"double"},{"type":"string","format":"date-time"}],"description":"Event timestamp","title":"DocumentProcessedEventTimestamp"},"DocumentProcessedEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/DocumentProcessedEventType","description":"The type of event"},"data":{"$ref":"#/components/schemas/DocumentData","description":"Event payload with document information"},"id":{"type":"string","description":"Unique identifier for this event (use for idempotent processing)"},"version":{"type":"string","description":"Version of the event schema"},"timestamp":{"$ref":"#/components/schemas/DocumentProcessedEventTimestamp","description":"Event timestamp"},"url":{"type":"string","description":"URL field (typically empty string for security)"}},"required":["type","data","id","version","timestamp"],"description":"Base event structure for document.* events","title":"DocumentProcessedEvent"},"DocumentApprovedEventType":{"type":"string","enum":["document.approved"],"description":"The type of event","title":"DocumentApprovedEventType"},"DocumentApprovedEventTimestamp":{"oneOf":[{"type":"number","format":"double"},{"type":"string","format":"date-time"}],"description":"Event timestamp","title":"DocumentApprovedEventTimestamp"},"DocumentApprovedEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/DocumentApprovedEventType","description":"The type of event"},"data":{"$ref":"#/components/schemas/DocumentData","description":"Event payload with document information"},"id":{"type":"string","description":"Unique identifier for this event (use for idempotent processing)"},"version":{"type":"string","description":"Version of the event schema"},"timestamp":{"$ref":"#/components/schemas/DocumentApprovedEventTimestamp","description":"Event timestamp"},"url":{"type":"string","description":"URL field (typically empty string for security)"}},"required":["type","data","id","version","timestamp"],"description":"Base event structure for document.* events","title":"DocumentApprovedEvent"},"DocumentDiscardedEventType":{"type":"string","enum":["document.discarded"],"description":"The type of event","title":"DocumentDiscardedEventType"},"DocumentDiscardedEventTimestamp":{"oneOf":[{"type":"number","format":"double"},{"type":"string","format":"date-time"}],"description":"Event timestamp","title":"DocumentDiscardedEventTimestamp"},"DocumentDiscardedEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/DocumentDiscardedEventType","description":"The type of event"},"data":{"$ref":"#/components/schemas/DocumentData","description":"Event payload with document information"},"id":{"type":"string","description":"Unique identifier for this event (use for idempotent processing)"},"version":{"type":"string","description":"Version of the event schema"},"timestamp":{"$ref":"#/components/schemas/DocumentDiscardedEventTimestamp","description":"Event timestamp"},"url":{"type":"string","description":"URL field (typically empty string for security)"}},"required":["type","data","id","version","timestamp"],"description":"Base event structure for document.* events","title":"DocumentDiscardedEvent"},"FileProcessedEventType":{"type":"string","enum":["file.processed"],"description":"The type of event","title":"FileProcessedEventType"},"FileProcessedEventDataStatus":{"type":"string","enum":["processed"],"description":"File status","title":"FileProcessedEventDataStatus"},"FileProcessedEventDataClientData":{"type":"object","properties":{},"description":"Client-provided metadata","title":"FileProcessedEventDataClientData"},"FileProcessedEventData":{"type":"object","properties":{"id":{"type":"string","description":"File identifier"},"accountId":{"type":"string","description":"Account identifier"},"environmentId":{"type":"string","description":"Environment identifier"},"importId":{"type":"string","description":"Import identifier"},"status":{"$ref":"#/components/schemas/FileProcessedEventDataStatus","description":"File status"},"filename":{"type":"string","description":"Name of the file"},"documentIds":{"type":"array","items":{"type":"string"},"description":"Array of document IDs generated from this file (flattened)"},"compressed":{"type":"boolean","description":"True if this is a compressed file (ZIP)"},"parentFileId":{"type":"string","description":"Parent file identifier (for files extracted from ZIP)"},"clientData":{"$ref":"#/components/schemas/FileProcessedEventDataClientData","description":"Client-provided metadata"}},"required":["id","accountId","environmentId","status","filename","documentIds"],"description":"Event payload with relevant information","title":"FileProcessedEventData"},"FileProcessedEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/FileProcessedEventType","description":"The type of event"},"version":{"type":"string","description":"Version of the event schema"},"id":{"type":"string","description":"Unique identifier for this event (use for idempotent processing)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the event occurred"},"data":{"$ref":"#/components/schemas/FileProcessedEventData","description":"Event payload with relevant information"}},"required":["type","version","id","timestamp","data"],"description":"Base event structure for file.* and import.* events","title":"FileProcessedEvent"},"FileRejectedEventType":{"type":"string","enum":["file.rejected"],"description":"The type of event","title":"FileRejectedEventType"},"FileRejectedEventDataStatus":{"type":"string","enum":["rejected"],"description":"File status","title":"FileRejectedEventDataStatus"},"FileRejectedEventDataError":{"type":"string","enum":["ERR_DOWNLOADING_FILE","ERR_UNSUPPORTED_FILE_FORMAT","ERR_UNSUPPORTED_UNCOMPRESSED_FILE_FORMAT","ERR_HASH","ERR_ZIP_ENCRYPTED","ERR_ZIP_DECOMPRESSION_FAILED","ERR_PROCESSING_ZIP_ENTRY"],"description":"Error code indicating why the file was rejected","title":"FileRejectedEventDataError"},"FileRejectedEventDataClientData":{"type":"object","properties":{},"description":"Client-provided metadata","title":"FileRejectedEventDataClientData"},"FileRejectedEventData":{"type":"object","properties":{"id":{"type":"string","description":"File identifier"},"accountId":{"type":"string","description":"Account identifier"},"environmentId":{"type":"string","description":"Environment identifier"},"importId":{"type":"string","description":"Import identifier"},"status":{"$ref":"#/components/schemas/FileRejectedEventDataStatus","description":"File status"},"filename":{"type":"string","description":"Name of the rejected file"},"error":{"$ref":"#/components/schemas/FileRejectedEventDataError","description":"Error code indicating why the file was rejected"},"parentFileId":{"type":"string","description":"Parent file identifier (for files extracted from ZIP)"},"clientData":{"$ref":"#/components/schemas/FileRejectedEventDataClientData","description":"Client-provided metadata"}},"required":["id","accountId","environmentId","importId","status","filename","error"],"description":"Event payload with relevant information","title":"FileRejectedEventData"},"FileRejectedEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/FileRejectedEventType","description":"The type of event"},"version":{"type":"string","description":"Version of the event schema"},"id":{"type":"string","description":"Unique identifier for this event (use for idempotent processing)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the event occurred"},"data":{"$ref":"#/components/schemas/FileRejectedEventData","description":"Event payload with relevant information"}},"required":["type","version","id","timestamp","data"],"description":"Base event structure for file.* and import.* events","title":"FileRejectedEvent"},"ImportProcessedEventType":{"type":"string","enum":["import.processed"],"description":"The type of event","title":"ImportProcessedEventType"},"ImportProcessedEventDataStatus":{"type":"string","enum":["processed"],"description":"Import status","title":"ImportProcessedEventDataStatus"},"ImportProcessedEventDataFilesItemsStatus":{"type":"string","enum":["processed","rejected"],"description":"File processing status","title":"ImportProcessedEventDataFilesItemsStatus"},"ImportProcessedEventDataFilesItemsError":{"type":"string","enum":["ERR_DOWNLOADING_FILE","ERR_UNSUPPORTED_FILE_FORMAT","ERR_UNSUPPORTED_UNCOMPRESSED_FILE_FORMAT","ERR_HASH","ERR_ZIP_ENCRYPTED","ERR_ZIP_DECOMPRESSION_FAILED","ERR_PROCESSING_ZIP_ENTRY"],"description":"Error code for rejected files (only present when status is \"rejected\")","title":"ImportProcessedEventDataFilesItemsError"},"ImportProcessedEventDataFilesItemsClientData":{"type":"object","properties":{},"description":"Client-provided metadata for this file","title":"ImportProcessedEventDataFilesItemsClientData"},"ImportProcessedEventDataFilesItems":{"type":"object","properties":{"id":{"type":"string","description":"File ID"},"status":{"$ref":"#/components/schemas/ImportProcessedEventDataFilesItemsStatus","description":"File processing status"},"filename":{"type":"string","description":"Name of the file"},"documentIds":{"type":"array","items":{"type":"string"},"description":"Array of document IDs generated from this file"},"error":{"$ref":"#/components/schemas/ImportProcessedEventDataFilesItemsError","description":"Error code for rejected files (only present when status is \"rejected\")"},"clientData":{"$ref":"#/components/schemas/ImportProcessedEventDataFilesItemsClientData","description":"Client-provided metadata for this file"}},"required":["id","status","filename","documentIds"],"title":"ImportProcessedEventDataFilesItems"},"ImportProcessedEventData":{"type":"object","properties":{"id":{"type":"string","description":"Import ID"},"accountId":{"type":"string","description":"Account identifier"},"environmentId":{"type":"string","description":"Environment identifier"},"status":{"$ref":"#/components/schemas/ImportProcessedEventDataStatus","description":"Import status"},"files":{"type":"array","items":{"$ref":"#/components/schemas/ImportProcessedEventDataFilesItems"},"description":"Array of files processed in this import"}},"required":["id","accountId","environmentId","status","files"],"description":"Event payload with relevant information","title":"ImportProcessedEventData"},"ImportProcessedEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ImportProcessedEventType","description":"The type of event"},"version":{"type":"string","description":"Version of the event schema"},"id":{"type":"string","description":"Unique identifier for this event (use for idempotent processing)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the event occurred"},"data":{"$ref":"#/components/schemas/ImportProcessedEventData","description":"Event payload with relevant information"}},"required":["type","version","id","timestamp","data"],"description":"Base event structure for file.* and import.* events","title":"ImportProcessedEvent"}}}}