{"openapi":"3.1.0","info":{"title":"POST /api/v1/invoices/ai-create","version":"1.0.0","description":"AI-extract draft invoices from documents"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/invoices/ai-create":{"post":{"tags":["invoices"],"summary":"AI-extract draft invoices from documents","description":"Upload pasted text, PDFs, images, Excel files, or a CSV to extract draft invoice entities using AI. Returns draft invoices ready for user review before creation.","operationId":"ai_create_invoice_payload_api_v1_invoices_ai_create_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceAICreatePayloadRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceAICreatePayloadResponse"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"detail":"Invalid request parameters"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"detail":"Not enough permissions"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"DraftInvoice":{"properties":{"customer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Name","description":"Customer/company name extracted by AI. Use to match or create a customer."},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Total invoice amount in cents extracted by AI."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Invoice description or notes."},"invoice_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Number","description":"Invoice number from the document."},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issue Date","description":"Invoice issue date (YYYY-MM-DD) extracted by AI."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due Date","description":"Payment due date (YYYY-MM-DD) extracted by AI."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes","description":"Additional notes or terms extracted by AI."},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Id","description":"Matched customer UUID (if the customer was found in the system)."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency code (USD, CAD, AUD, EUR, or GBP). Defaults to USD.","default":"USD"},"line_items":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Line Items","description":"Line items extracted by AI: [{description, quantity, unit_price_cents, total_cents}]."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of the source document for this invoice."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"AI confidence score for this extraction (0.0-1.0)."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source type: 'pasted_text', 'single_file', or 'multi_file'."},"source_filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Filename","description":"Original filename or S3 key of the source document."}},"type":"object","title":"DraftInvoice","description":"A draft invoice entity extracted by AI, ready for user review before creation.\n\nIncludes all fields needed for creating an invoice. Fields are optional\nsince AI extraction may not populate every field.","example":{"amount":25000,"confidence":0.88,"currency":"USD","customer_name":"Acme Corporation","description":"Consulting services - January 2026","due_date":"2026-03-03","invoice_number":"INV-001","issue_date":"2026-02-01","line_items":[{"description":"Consulting - 10 hours","quantity":10,"total_cents":25000,"unit_price_cents":2500}],"source":"single_file"}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InvoiceAICreatePayloadRequest":{"properties":{"pasted_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pasted Text","description":"Raw text content to extract an invoice from. Limit 1 invoice per text input. Mutually exclusive with pasted_text_s3_key."},"pasted_text_s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pasted Text S3 Key","description":"S3 key of pasted text content. Limit 1 invoice per text input. Mutually exclusive with pasted_text."},"single_invoice_s3_keys":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Single Invoice S3 Keys","description":"S3 keys of individual invoice documents (PDFs, images, Excel). Each file is processed independently."},"multi_invoice_s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Multi Invoice S3 Key","description":"S3 key of a CSV file containing multiple invoices."}},"type":"object","title":"InvoiceAICreatePayloadRequest","description":"Request schema for AI-powered invoice extraction from uploaded documents.\n\nProvide one or more source inputs. The AI will analyze each source and\nextract draft invoice entities from the content.\n\nSource types:\n- pasted_text: Raw text content to extract an invoice from (limit 1 invoice)\n- pasted_text_s3_key: S3 key of pasted text content (limit 1 invoice)\n- single_invoice_s3_keys: S3 keys of individual invoice documents (PDFs, images, Excel)\n- multi_invoice_s3_key: S3 key of a CSV or Excel file containing multiple invoices","example":{"single_invoice_s3_keys":["business-id/uuid-invoice1.pdf","business-id/uuid-invoice2.png"]}},"InvoiceAICreatePayloadResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DraftInvoice"},"type":"array","title":"Items","description":"List of draft invoice entities extracted by AI."},"errors":{"items":{"$ref":"#/components/schemas/InvoiceFileProcessingError"},"type":"array","title":"Errors","description":"List of per-file errors for files that could not be processed."}},"type":"object","required":["items"],"title":"InvoiceAICreatePayloadResponse","description":"Response schema for AI-powered invoice extraction.\n\nReturns a list of draft invoice entities extracted from the uploaded documents.\nFiles that fail are reported in the ``errors`` list rather than causing\nthe entire request to fail.","example":{"errors":[],"items":[{"amount":25000,"confidence":0.88,"currency":"USD","customer_name":"Acme Corporation","description":"Consulting services","due_date":"2026-03-03","invoice_number":"INV-001","source":"single_file"}]}},"InvoiceFileProcessingError":{"properties":{"s3_key":{"type":"string","title":"S3 Key","description":"S3 key of the file that failed."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename","description":"Original filename (if determinable from the S3 key)."},"error":{"type":"string","title":"Error","description":"Human-readable error description."}},"type":"object","required":["s3_key","error"],"title":"InvoiceFileProcessingError","description":"Error detail for a file that failed during AI extraction."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}