> ## Documentation Index > Fetch the complete documentation index at: https://docs.dolfinai.co/llms.txt > Use this file to discover all available pages before exploring further. # Retry bill extraction > Retry extraction for a bill in the ExtractionFailed state. **Authentication.** An API key (`x-dolfin-api-key`) **together with** the `x-dolfin-organisation-id` header identifying the organisation, **or** a JWT Bearer token that carries the organisation in its claims. ## OpenAPI ````yaml post /v1/bills/{id}/retry-extraction openapi: 3.1.1 info: title: Dolfin API description: >- Dolfin API for AR & AP. Each operation documents its accepted credentials under **Authentication** — typically an `x-dolfin-api-key` header (with `x-dolfin-organisation-id`) or a JWT Bearer token. version: v1 servers: - url: https://api.dolfinai.co description: Production security: [] tags: - name: Users - name: TaxRates - name: Suppliers - name: Supplier Credit Notes - name: Bills - name: Payables - name: RecurringInvoices - name: Receivables - name: Purchase Orders - name: Products - name: Payments - name: Invoices - name: Organisations - name: Clients - name: MCP - name: Matching - name: Invoice Reminders - name: Industries - name: Gmail - name: Delivery Notes - name: Customers - name: Currencies - name: Credit Notes - name: Companies - name: BankPayments - name: Bank details - name: Auth - name: ApprovalPolicies - name: Agent paths: /v1/bills/{id}/retry-extraction: post: tags: - Bills summary: Retry bill extraction description: >- Retry extraction for a bill in the ExtractionFailed state. **Authentication.** An API key (`x-dolfin-api-key`) **together with** the `x-dolfin-organisation-id` header identifying the organisation, **or** a JWT Bearer token that carries the organisation in its claims. parameters: - name: id in: path required: true schema: type: string format: uuid - name: x-dolfin-organisation-id in: header description: >- Target organisation. **Required when authenticating with an API key**; omit for Bearer callers (resolved from the token). schema: type: string format: uuid responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/BillResponse' '400': description: >- Bill.TransitionFailed — bill is not in a state that allows this transition content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '403': description: >- Module.NotEntitled — the client's plan does not include the module this endpoint requires content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: >- Bill.NotFound — bill does not exist or belongs to a different organisation content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '409': description: >- Request.Conflict — another change to the same record landed first; retry the request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: Request.Failed — the command failed while being processed content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '504': description: >- Gateway Timeout Request.Timeout — the command did not complete in time; it may still be applied content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - ApiKey: [] - Bearer: [] components: schemas: BillResponse: type: object properties: id: type: string format: uuid organisationId: type: string format: uuid state: $ref: '#/components/schemas/BillState' source: $ref: '#/components/schemas/BillSource' fileName: type: - 'null' - string rawFileType: type: - 'null' - string supplierId: type: - 'null' - string format: uuid suggestedMatchedSupplierId: type: - 'null' - string description: >- Suggested supplier match. Auto-accepted as the Supplier on review submit if Supplier is not set. Found in tiers: exact tax id / email, then exact name, then a fuzzy weighted name + delivery-address match. format: uuid suggestedMatchedSupplierConfidence: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string description: >- Confidence (0-1) of SuggestedMatchedSupplierId: 1.0 for a tax-id/email hit, ~0.95 for an exact name, and the computed weighted score for a fuzzy hit. Null when there is no suggestion. Use it to grade how the suggestion is surfaced (e.g. ask for confirmation below a threshold). format: double supplierName: type: - 'null' - string supplierEmail: type: - 'null' - string supplierPhone: type: - 'null' - string supplierAddress: type: - 'null' - string deliveryAddress: type: - 'null' - string description: >- Ship-to / delivery address as printed on the bill, weighed against the supplier's address in fuzzy matching. supplierAddressDetail: oneOf: - type: 'null' - $ref: '#/components/schemas/Address' description: >- The supplier's address as components, extracted from the document. Null when the document's address block could not be broken down. deliveryAddressDetail: oneOf: - type: 'null' - $ref: '#/components/schemas/Address' description: >- The delivery address as components, extracted from the document. This is what is matched against an organisation's address when routing a bill received against a company. Null when the document's address block could not be broken down. supplierTaxId: type: - 'null' - string supplierWebsite: type: - 'null' - string supplierRegistrationNumber: type: - 'null' - string invoiceNumber: type: - 'null' - string invoiceDate: type: - 'null' - string format: date-time dueDate: type: - 'null' - string format: date-time currency: type: string description: ISO 4217 currency code (e.g. GBP, USD, EUR) subTotal: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double taxAmount: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double totalAmount: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double amountCredited: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string description: Supplier credit netted against this bill. format: double outstanding: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string description: >- What's left to pay after supplier credit (TotalAmount − AmountCredited). This is what the payment flow charges. format: double paymentTerms: type: - 'null' - string paymentRef: type: - 'null' - string bankDetails: $ref: '#/components/schemas/BankDetails' confidence: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string description: >- Extraction confidence (0-1) reported by the extractor. Null until extraction completes. format: float approvedBy: type: - 'null' - string format: uuid approvedAt: type: - 'null' - string format: date-time rejectedBy: type: - 'null' - string format: uuid rejectedAt: type: - 'null' - string format: date-time rejectionReason: type: - 'null' - string voidedBy: type: - 'null' - string description: >- Set when Voided. A null VoidedBy with a non-null VoidedAt ⇒ policy auto-void. format: uuid voidedAt: type: - 'null' - string format: date-time voidReason: type: - 'null' - string duplicateOfBillId: type: - 'null' - string description: >- The earlier bill this one appears to duplicate — same organisation, same supplier, same invoice number. Null when no duplicate was found. While set and not yet confirmed as a false alarm, the bill cannot be approved; confirm it is not a duplicate to clear that, or void it. format: uuid duplicateDetectedAt: type: - 'null' - string description: >- When the possible duplicate was detected, which happens automatically just after the bill's document is extracted. format: date-time duplicateMatchBasis: oneOf: - type: 'null' - $ref: '#/components/schemas/DuplicateMatchBasis' description: >- Which evidence matched: SupplierId means both bills resolve to the same supplier record; SupplierName means only their extracted supplier names agree, which is a weaker signal worth checking more carefully. duplicateDismissedAt: type: - 'null' - string description: >- When someone confirmed this bill is not a duplicate. Once set, the bill can be approved; duplicateOfBillId is kept so the link to the other bill stays visible. format: date-time appliedApprovalPolicyId: type: - 'null' - string description: The approval policy applied at submit-review, if any (UI badge). format: uuid appliedApprovalPolicyName: type: - 'null' - string approvalReasoning: type: - 'null' - string description: Deterministic explanation of the approval decision. resolvedApproverUserIds: type: array items: type: string format: uuid description: >- Users this bill was routed to for approval — the pending reviewers while in NeedsApproval. paymentDate: type: - 'null' - string format: date-time paymentMethod: type: - 'null' - string paidAt: type: - 'null' - string format: date-time createdAt: type: string format: date-time createdBy: type: - 'null' - string format: uuid updatedAt: type: string format: date-time updatedBy: type: - 'null' - string format: uuid matchSummary: oneOf: - type: 'null' - $ref: '#/components/schemas/BillMatchSummary' description: >- Three-way match facts for this bill: the match status plus the purchase orders and delivery notes it is matched to. Null means the bill has no match group at all, which is the normal state when there was no candidate purchase order; it does not mean 'unmatched pending'. Only populated when the request asks for it (includeMatch=true) — otherwise it is always null. Fetch the bill's match group for the per-line detail and suggestions behind the summary. supplier: oneOf: - type: 'null' - $ref: '#/components/schemas/SupplierResponse' lineItems: type: array items: $ref: '#/components/schemas/BillLineItemResponse' tags: type: array items: type: string description: >- Distinct union of the line items' tags, baked at submit-review — for bill-level filtering. ProblemDetails: type: object properties: type: type: - 'null' - string title: type: - 'null' - string status: pattern: ^-?(?:0|[1-9]\d*)$ type: - 'null' - integer - string format: int32 detail: type: - 'null' - string instance: type: - 'null' - string BillState: enum: - Created - Extracting - PendingReview - NeedsApproval - Approved - Rejected - Scheduled - Paid - ExtractionFailed - PaymentInProgress - PaymentFailed - Voided - OcrProcessing - OcrFailed BillSource: enum: - Upload - Email - Webhook Address: type: object properties: line1: type: - 'null' - string line2: type: - 'null' - string city: type: - 'null' - string state: type: - 'null' - string postalCode: type: - 'null' - string country: type: - 'null' - string description: ISO 3166-1 alpha-2 country code (e.g. GB, US, DE) isEmpty: type: boolean BankDetails: type: object properties: accountHolderName: type: - 'null' - string accountNumber: type: - 'null' - string sortCode: type: - 'null' - string routingNumber: type: - 'null' - string iban: type: - 'null' - string bicSwift: type: - 'null' - string country: type: - 'null' - string description: ISO 3166-1 alpha-2 country code (e.g. GB, US, DE) currency: type: - 'null' - string description: ISO 4217 currency code (e.g. GBP, USD, EUR) DuplicateMatchBasis: enum: - SupplierId - SupplierName - null BillMatchSummary: required: - status - matchedPurchaseOrders - matchedDeliveryNotes type: object properties: status: $ref: '#/components/schemas/MatchGroupStatus' description: >- Lifecycle status of the bill's match: Open (a match group exists but nothing is allocated yet), Variance (a flagged difference awaits a human decision), Resolved (every line settled — either a clean match or a human-accepted variance), or Synced (exported). matchedPurchaseOrders: type: array items: $ref: '#/components/schemas/MatchedDocumentRef' description: >- Distinct purchase orders this bill has confirmed allocations against, ordered by number. Empty when the match group exists but nothing is matched yet, or when only delivery notes are matched. More than one entry means the bill spans several orders. matchedDeliveryNotes: type: array items: $ref: '#/components/schemas/MatchedDocumentRef' description: >- Distinct delivery notes this bill has confirmed allocations against, ordered by number. Empty on a two-way (price-only) match, where the receipt side was never matched. description: >- Stored three-way match facts for a bill: the match group's lifecycle status and the purchase orders and delivery notes its confirmed allocations point at. Per-line detail and variances are not here — fetch the bill's match group for those. SupplierResponse: required: - name type: object properties: id: type: string format: uuid organisationId: type: string format: uuid name: type: string email: type: - 'null' - string phone: type: - 'null' - string website: type: - 'null' - string taxNumber: type: - 'null' - string registrationNumber: type: - 'null' - string address: oneOf: - type: 'null' - $ref: '#/components/schemas/Address' bankDetails: $ref: '#/components/schemas/BankDetails' bankDetailsVerified: type: boolean bankDetailsVerifiedAt: type: - 'null' - string format: date-time paymentTermsDefault: type: - 'null' - string createdAt: type: string format: date-time createdBy: type: - 'null' - string format: uuid updatedAt: type: string format: date-time updatedBy: type: - 'null' - string format: uuid BillLineItemResponse: required: - description type: object properties: id: type: string format: uuid description: type: string sku: type: - 'null' - string description: >- Optional product code / SKU as printed on the document. The exact-match key for three-way matching against PO/DN lines; null when the document omits it. quantity: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double unit: type: - 'null' - string description: >- Optional unit of measure as it appears on the document (e.g. kg, box, hrs). unitOfMeasure: oneOf: - type: 'null' - $ref: '#/components/schemas/UnitOfMeasure' description: >- Structured weight/volume unit (Gram, Kilogram, Millilitre, Litre) parsed from Unit for catch-weight matching; null when Unit is free text we don't recognise. unitPrice: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double taxRate: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string description: >- Tax rate as a percentage (e.g. 20 for 20%). Descriptive metadata only — TaxAmount is the authoritative figure and is not derived from this rate. format: double taxAmount: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double subTotal: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double sortOrder: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int32 category: type: - 'null' - string spendClass: oneOf: - type: 'null' - $ref: '#/components/schemas/SpendClass' tags: type: array items: type: string categoryConfirmed: type: boolean spendClassConfirmed: type: boolean suggestedCategory: type: - 'null' - string categoryConfidence: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string format: double suggestedSpendClass: oneOf: - type: 'null' - $ref: '#/components/schemas/SpendClass' spendClassConfidence: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string format: double MatchGroupStatus: enum: - Open - Variance - Resolved - Synced description: >- Lifecycle status of a match group: Open (nothing to settle), Variance (a flagged difference awaits a decision), Resolved (settled), or Synced (exported to accounting — not reachable yet). MatchedDocumentRef: required: - id - number type: object properties: id: type: string description: >- Unique identifier of the purchase order or delivery note. Use it to fetch the full document. format: uuid number: type: string description: >- The document's human-readable number as issued by Dolfin (the PO number or delivery-note number). externalRef: type: - 'null' - string description: >- The document's identifier in your own system, if one was supplied when it was created. Null when the document originated in Dolfin. Use it to reconcile a matched bill back to your ERP without storing Dolfin ids. description: A purchase order or delivery note that a bill is matched to. UnitOfMeasure: enum: - Gram - Kilogram - Millilitre - Litre - null SpendClass: enum: - Fixed - Variable - null securitySchemes: ApiKey: type: apiKey description: >- An API key issued to your client. It carries the client's scope; org-scoped calls also require the `x-dolfin-organisation-id` header. Keys are created and revoked by a client administrator. name: x-dolfin-api-key in: header Bearer: type: http description: >- A session JWT obtained via the OAuth flow (`POST /auth/codes` → `POST /auth/exchange`). Its claims carry the caller's organisation and/or client scope. scheme: bearer bearerFormat: JWT ````