Skip to content

Reference: schemas

Money amounts are decimal strings (for example "1234.56"), never floating point numbers. Dates are ISO 8601 strings.

Body of every error answer. message is plain text in German for people and logs: do not parse it. Rely on the HTTP status code and, where present, on code and params.

Field Type Required Description
statusCode integer yes HTTP status code, repeated in the body.
message string yes Plain text in German. Not stable, do not parse it.
error string no Name of the HTTP status, for example Not Found.
code string no Stable error code where one is assigned, for example approval.external_conflict. Not every error carries a code; use the status code then.
params object no Values that belong to the code, for example the status of an invoice.
issues array of object no Only on 400 for an invalid request: one entry per invalid field. path names the field, code is the violated validation rule and message is a German explanation.
issues[].path string no
issues[].code string no
issues[].message string no
retryAfterSeconds integer no Only on 429 from the rate limit: seconds until the next attempt, the same as the Retry-After header.

Health report of the instance. Further diagnostic fields may be added.

Field Type Required Description
status string yes ok when database, queue and file storage work, otherwise degraded. One of: ok, degraded.
checks object no Result of each check.
checks.database boolean no The database answers.
checks.queue boolean no The job queue runs and no job has been waiting for too long.
checks.storage boolean no The file storage is writable.
version string no Release of the running instance, or dev for a development build.
uptimeSeconds integer no Seconds since the process started.
Field Type Required Description
invoiceId string (uuid) yes Id of the created invoice, or of the existing one when duplicate is true.
status string yes Status of the invoice. See “Invoice status” in the API introduction. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
duplicate boolean yes true when the file or document was already known in this company. Then nothing new was created and the body names the existing invoice.
Field Type Required Description
items array of InvoiceListItem yes The invoices of the requested page.
total integer yes Number of invoices that match the filters, across all pages. Minimum 0. Maximum 9007199254740991.
page integer yes Number of this page, starting at 1. Minimum 1. Maximum 9007199254740991.
pageSize integer yes Number of invoices per page. Minimum 1. Maximum 9007199254740991.

One invoice in the list. getInvoice returns the full state.

Field Type Required Description
sourceFormat string yes One of: pdf, image, xrechnung, zugferd, facturx, peppol, en16931, ebinterface, eslog. Default: "pdf".
sourceProfile string, nullable yes Default: null.
isSample boolean yes Default: false.
id string (uuid) yes Id of the invoice.
companyId string (uuid) yes Id of the company the invoice belongs to.
companyName string, nullable no Name of the company.
status string yes Status of the invoice. See “Invoice status” in the API introduction. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
statusReason string, nullable no Reason for the status, for example approval_external. See “Invoice status” in the API introduction.
processing object, nullable no Progress while the invoice is being processed (captured, extracted): step, state, kind of error and time of the next automatic attempt. null outside processing.
processing.step string yes One of: preflight, ocr, extract, enrich, einvoice, suggest.
processing.state string yes One of: queued, running, retrying, waiting, failed.
processing.error string, nullable yes One of: unavailable, timeout, rate_limited, quota, auth, config, document, ai_response, internal, license.
processing.retryAt string (date-time), nullable yes
processing.startedAt string (date-time), nullable yes
processing.since string (date-time) yes
needsClearance boolean yes Default: false.
clearanceNote string, nullable no
documentType string yes invoice or credit_note. One of: invoice, credit_note.
invoiceNumber string, nullable no Invoice number as printed on the document.
invoiceDate string (date), nullable no Invoice date.
dueDate string (date), nullable no Due date.
currency string yes Currency of the document (ISO 4217). Pattern: ^[A-Z]{3}$.
netTotal string, nullable no Net total as a decimal string. Pattern: ^-?\d+(\.\d+)?$.
grossTotal string, nullable no Gross total as a decimal string. Pattern: ^-?\d+(\.\d+)?$.
vendorId string (uuid), nullable no Id of the matched vendor, if any.
vendorName string, nullable no Name of the matched vendor, if any.
subVendorName string, nullable no
vendorMatchConfidence number, nullable no Minimum 0. Maximum 1.
discountDueDate string (date), nullable no
discountAmount string, nullable no Pattern: ^-?\d+(\.\d+)?$.
paymentMethod object, nullable yes Default: null.
paymentMethod.id string (uuid) yes
paymentMethod.label string yes
paymentMethod.kind string yes One of: cash, credit_card, bank_transfer, private_outlay, direct_debit, debit_card, online.
paymentMethod.cardLast4 string, nullable yes
deletedAt string (date-time), nullable no
deletedByUserId string, nullable no
deletedByName string, nullable no
deletedFromStatus string, nullable no One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
deleteReason string, nullable no
createdAt string (date-time) yes When fineelik received the document.
updatedAt string (date-time) yes When the invoice was last changed.

The full state of an invoice: header and line data, account coding, approval and payment state, references (duplicate, reversal) and validation findings.

Field Type Required Description
sourceFormat string yes One of: pdf, image, xrechnung, zugferd, facturx, peppol, en16931, ebinterface, eslog. Default: "pdf".
sourceProfile string, nullable yes Default: null.
isSample boolean yes Default: false.
intakeItem object, nullable yes Default: null.
intakeItem.id string (uuid) yes
intakeItem.status string yes One of: open, assigned, done, processed.
intakeItem.documentType string yes One of: invoice, credit_note, delivery_note, order_confirmation, purchase_order, dunning, offer, contract, other, unknown, payment_receipt.
intakeItem.assignedInvoice object, nullable yes
intakeItem.assignedInvoice.id string (uuid) yes
intakeItem.assignedInvoice.invoiceNumber string, nullable yes
tip object, nullable yes Default: null.
tip.amount string yes
tip.paidAmount string, nullable yes
tip.basis string yes One of: printed, paid_difference.
tip.mode string yes One of: off, notice, line.
tip.modeSource string yes One of: sub_vendor, vendor, company.
tip.state string yes One of: booked, open, above_limit, ignored.
tip.proposal object yes
tip.proposal.description string yes
tip.proposal.taxRate string yes
tip.proposal.netAmount string yes
tip.proposal.taxAmount string yes
tip.proposal.grossAmount string yes
tip.proposal.dimensions object yes
einvoiceReview object, nullable yes Default: null.
einvoiceReview.formalMode string yes One of: hint, block.
einvoiceReview.formalChecked boolean yes
einvoiceReview.formalValid boolean, nullable yes
einvoiceReview.formalErrorCount integer yes Minimum 0. Maximum 9007199254740991.
einvoiceReview.formalAcceptedAt string (date-time), nullable yes
einvoiceReview.formalAcceptedByName string, nullable yes
einvoiceReview.formalBlocking boolean yes
einvoiceReview.prepaidAmount string, nullable yes Pattern: ^-?\d+(\.\d+)?$.
einvoiceReview.prepaymentRecorded boolean yes
matchReview object, nullable yes Default: null.
matchReview.mode string yes One of: clearance, block.
matchReview.deviations integer yes Minimum 0. Maximum 9007199254740991.
matchReview.quantityDeviations integer yes Minimum 0. Maximum 9007199254740991.
matchReview.orderDeviations integer yes Minimum 0. Maximum 9007199254740991.
matchReview.confirmed boolean yes
matchReview.confirmedAt string (date-time), nullable yes
matchReview.confirmedByName string, nullable yes
matchReview.blocking boolean yes
agreementMatch object, nullable yes Contract block (module “Contracts”): the assignments of the invoice to contracts and their check. null without the module. An API key is never a named viewer: for a confidential contract an assignment has visibility limited, then contract, payment line, amounts, tolerance, score and the parameters of the checks are empty and only the result and the check codes remain. Default: null.
agreementMatch.mode string yes One of: clearance, block.
agreementMatch.links array of object yes Active assignments, also suggestions.
agreementMatch.links[].id string (uuid) yes
agreementMatch.links[].visibility string yes One of: full, limited.
agreementMatch.links[].confidential boolean yes
agreementMatch.links[].agreement object, nullable yes
agreementMatch.links[].agreement.id string (uuid) yes
agreementMatch.links[].agreement.number string yes
agreementMatch.links[].agreement.title string yes
agreementMatch.links[].agreement.vendorId string (uuid), nullable yes
agreementMatch.links[].agreement.vendorName string, nullable yes
agreementMatch.links[].agreement.counterpartyName string, nullable yes
agreementMatch.links[].agreement.managedBy string yes One of: fineelik, elo. Default: "fineelik".
agreementMatch.links[].paymentLine object, nullable yes
agreementMatch.links[].paymentLine.id string (uuid) yes
agreementMatch.links[].paymentLine.description string yes
agreementMatch.links[].paymentLine.cycle string yes One of: one_time, daily, weekly, biweekly, monthly, quarterly, half_yearly, yearly.
agreementMatch.links[].paymentLine.kind string yes One of: fixed, variable.
agreementMatch.links[].paymentLine.objectNumber string, nullable yes
agreementMatch.links[].matchSource string yes One of: auto, suggested, manual.
agreementMatch.links[].matchRule string yes One of: contract_number, match_key, object_number, score, manual.
agreementMatch.links[].matchedKey string, nullable yes
agreementMatch.links[].score number, nullable yes
agreementMatch.links[].reasons array of object yes
agreementMatch.links[].reasons[].code string yes One of: contract_number, match_key, object_number, vendor, amount_exact, amount_in_tolerance, amount_near, period_cycle, in_term, weak_key, several_candidates, vendor_mismatch, vendor_unknown.
agreementMatch.links[].reasons[].params object yes
agreementMatch.links[].periodStart string (date), nullable yes
agreementMatch.links[].periodEnd string (date), nullable yes
agreementMatch.links[].periodCount integer yes Minimum -9007199254740991. Maximum 9007199254740991.
agreementMatch.links[].amountBasis string yes One of: net, gross.
agreementMatch.links[].currency string yes
agreementMatch.links[].expectedAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].actualAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].deviationAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].deviationPercent string, nullable yes
agreementMatch.links[].allowedUpAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].allowedDownAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].result string yes One of: ok, deviation, unchecked.
agreementMatch.links[].checks array of object yes
agreementMatch.links[].checks[].code string yes One of: amount_in_tolerance, amount_above, amount_below, amount_missing, no_payment_line, positions_unassigned, currency_mismatch, before_start, after_end, terminated, not_active, second_invoice_in_period, total_value_exceeded, total_value_near, variable_amount_unchecked, index_clause_present, price_increase, price_increase_over_limit.
agreementMatch.links[].checks[].severity string yes One of: ok, info, deviation.
agreementMatch.links[].checks[].params object yes
agreementMatch.links[].positions array of integer yes
agreementMatch.links[].confirmed boolean yes
agreementMatch.links[].confirmedAt string (date-time), nullable yes
agreementMatch.links[].confirmedByName string, nullable yes
agreementMatch.links[].deviationAccepted boolean yes
agreementMatch.links[].deviationAcceptedAt string (date-time), nullable yes
agreementMatch.links[].deviationAcceptedByName string, nullable yes
agreementMatch.links[].checkedAt string (date-time) yes
agreementMatch.deviations integer yes Minimum 0. Maximum 9007199254740991.
agreementMatch.blocking boolean yes true when the company blocks on deviations and a deviation is not confirmed yet.
agreementMatch.outcome string yes Result for the whole invoice: ok, deviation, unchecked, suggested, partial (not fully assigned) or none. One of: ok, deviation, unchecked, suggested, partial, none.
agreementMatch.autoApproval object, nullable yes Decision of the automatic approval when the approval started inside fineelik, or null when none was taken (before the start, without contract, or when the approval runs in the leading system). blockers lists the reasons against as codes, see agreementMatch.blockers in InvoiceExport.
agreementMatch.autoApproval.possible boolean yes
agreementMatch.autoApproval.autoApproved boolean yes
agreementMatch.autoApproval.decidedAt string (date-time) yes
agreementMatch.autoApproval.outcome string yes One of: ok, deviation, unchecked, suggested, partial, none.
agreementMatch.autoApproval.blockers array of string yes
dmsTransfer object, nullable yes Default: null.
dmsTransfer.state string yes One of: waiting, failed.
dmsTransfer.attempts integer yes Minimum 0. Maximum 9007199254740991.
dmsTransfer.lastError string, nullable yes
dmsTransfer.nextAttemptAt string (date-time), nullable yes
id string (uuid) yes Id of the invoice.
status string yes Status of the invoice. See “Invoice status” in the API introduction. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
statusReason string, nullable no Reason for the status, for example approval_external. See “Invoice status” in the API introduction.
processing object, nullable no Progress while the invoice is being processed (captured, extracted): step, state (queued, running, retrying, waiting, failed), kind of error and time of the next automatic attempt. null outside processing.
processing.step string yes One of: preflight, ocr, extract, enrich, einvoice, suggest.
processing.state string yes One of: queued, running, retrying, waiting, failed.
processing.error string, nullable yes One of: unavailable, timeout, rate_limited, quota, auth, config, document, ai_response, internal, license.
processing.retryAt string (date-time), nullable yes
processing.startedAt string (date-time), nullable yes
processing.since string (date-time) yes
suggestionsPending boolean no
pageRotation integer no Minimum 0. Maximum 270.
captureChannel string yes Channel through which the document arrived (for example upload or dms). One of: dms, email, upload, api, expense, import, reversal.
externalDocumentLink object, nullable yes Default: null.
externalDocumentLink.provider string yes One of: elo.
externalDocumentLink.url string (uri) yes
documentType string yes invoice or credit_note. One of: invoice, credit_note.
invoiceNumber string, nullable no Invoice number as printed on the document.
invoiceDate string (date), nullable no Invoice date.
dueDate string (date), nullable no Due date.
dueDateSource string, nullable no One of: extraction, payment_term, vendor_default, invoice_date, manual.
paymentMethod object, nullable yes Default: null.
paymentMethod.id string (uuid) yes
paymentMethod.label string yes
paymentMethod.kind string yes One of: cash, credit_card, bank_transfer, private_outlay, direct_debit, debit_card, online.
paymentMethod.cardLast4 string, nullable yes
paymentMethodSource string, nullable no One of: extraction, vendor_default, company_default, manual.
paymentHint object, nullable yes Default: null.
paymentHint.method string yes One of: bank_transfer, direct_debit, credit_card, debit_card, online, cash, unknown.
paymentHint.status string yes One of: open, paid, will_be_debited, unknown.
paymentHint.cardLast4 string, nullable yes
paymentHint.evidence string, nullable yes
paymentMethodWarnings array of string yes Default: [].
servicePeriodStart string (date), nullable no Start of the service period according to the document, if named.
servicePeriodEnd string (date), nullable no End of the service period according to the document, if named.
currency string yes Currency of the document (ISO 4217). Pattern: ^[A-Z]{3}$.
netTotal string, nullable no Net total as a decimal string. Pattern: ^-?\d+(\.\d+)?$.
grossTotal string, nullable no Gross total as a decimal string. Pattern: ^-?\d+(\.\d+)?$.
taxAmounts array of object yes Tax amounts by tax rate.
taxAmounts[].taxRate string yes Pattern: ^-?\d+(\.\d+)?$.
taxAmounts[].netAmount string yes Pattern: ^-?\d+(\.\d+)?$.
taxAmounts[].taxAmount string yes Pattern: ^-?\d+(\.\d+)?$.
reverseCharge boolean yes Default: false.
reverseChargeSource string yes One of: manual, sub_vendor, vendor, group, country, document. Default: "document".
reverseChargeInputs object yes Default: {"override":"auto","documentHint":false,"subVendorOverride":null,"vendorOverride":null,"vendorBusinessPostingGroup":null,"groupDefaults":{},"countryDefault":null}.
reverseChargeInputs.override string yes One of: auto, ignore, force.
reverseChargeInputs.documentHint boolean yes
reverseChargeInputs.subVendorOverride string, nullable yes One of: auto, ignore, force.
reverseChargeInputs.vendorOverride string, nullable yes One of: auto, ignore, force.
reverseChargeInputs.vendorBusinessPostingGroup string, nullable yes
reverseChargeInputs.groupDefaults object yes
reverseChargeInputs.countryDefault boolean, nullable yes Default: null.
paymentTerms object, nullable no The payment term that fineelik applies (the best valid one).
paymentTerms.dueDate string (date), nullable no
paymentTerms.discountDays integer, nullable no Minimum 0. Maximum 9007199254740991.
paymentTerms.discountPercent string, nullable no Pattern: ^-?\d+(\.\d+)?$.
paymentTerms.discountAmount string, nullable no Pattern: ^-?\d+(\.\d+)?$.
paymentTermsList array of object yes
paymentTermsList[].rank integer yes Minimum 1. Maximum 9007199254740991.
paymentTermsList[].dueDate string (date), nullable no
paymentTermsList[].discountDays integer, nullable no Minimum 0. Maximum 9007199254740991.
paymentTermsList[].discountPercent string yes Pattern: ^-?\d+(\.\d+)?$.
paymentTermsList[].discountAmount string, nullable no Pattern: ^-?\d+(\.\d+)?$.
paymentTermsList[].source string yes One of: extraction, manual, erp_default.
originalPaymentTerms array of object yes
originalPaymentTerms[].rank integer yes Minimum 1. Maximum 9007199254740991.
originalPaymentTerms[].dueDate string (date), nullable no
originalPaymentTerms[].discountDays integer, nullable no Minimum 0. Maximum 9007199254740991.
originalPaymentTerms[].discountPercent string yes Pattern: ^-?\d+(\.\d+)?$.
originalPaymentTerms[].discountAmount string, nullable no Pattern: ^-?\d+(\.\d+)?$.
orders array of object yes
orders[].orderNumber string yes
orders[].orderDate string (date), nullable no
company object yes The company the invoice belongs to.
company.id string (uuid) yes
company.code string yes
company.name string yes
company.vatId string, nullable no
company.defaultCurrency string no Pattern: ^[A-Z]{3}$.
company.countryCode string, nullable no
recipient object yes
recipient.name string, nullable yes
recipient.vatId string, nullable yes
recipient.taxNumber string, nullable yes Default: null.
recipient.state string yes One of: match, not_on_document, mismatch, other_company.
recipient.taxNumberDiffers object, nullable yes Default: null.
recipient.taxNumberDiffers.printed string yes
recipient.taxNumberDiffers.own string yes
recipient.suggestedCompany object, nullable yes
recipient.suggestedCompany.id string (uuid) yes
recipient.suggestedCompany.name string yes
vendor object, nullable no The matched vendor, if any.
vendor.id string (uuid) yes
vendor.name string yes
vendor.vatId string, nullable no
vendor.matchType string, nullable no
vendor.matchConfidence number, nullable no Minimum 0. Maximum 1.
vendor.paymentDefaults object, nullable no
vendor.paymentDefaults.termDays integer, nullable no Minimum 0. Maximum 9007199254740991.
vendor.paymentDefaults.discountPercent string, nullable no Pattern: ^-?\d+(\.\d+)?$.
vendor.paymentDefaults.discountDays integer, nullable no Minimum 0. Maximum 9007199254740991.
subVendor object, nullable no
subVendor.id string (uuid) yes
subVendor.code string yes
subVendor.name string yes
subVendor.vatId string, nullable no
subVendor.countryCode string, nullable no
subVendor.city string, nullable no
subVendor.hasIban boolean yes
collectiveSuggestion object, nullable no
collectiveSuggestion.vendorId string (uuid) yes
collectiveSuggestion.vendorName string yes
collectiveSuggestion.scope string yes One of: domestic, eu, non_eu, all.
collectiveSuggestion.proposed object yes
collectiveSuggestion.proposed.name string yes Up to 200 characters.
collectiveSuggestion.proposed.code string no Up to 50 characters.
collectiveSuggestion.proposed.vatId string, nullable no Up to 50 characters.
collectiveSuggestion.proposed.countryCode string, nullable no Up to 2 characters.
collectiveSuggestion.proposed.street string, nullable no Up to 200 characters.
collectiveSuggestion.proposed.zip string, nullable no Up to 20 characters.
collectiveSuggestion.proposed.city string, nullable no Up to 100 characters.
collectiveSuggestion.proposed.email string (email), nullable no
collectiveSuggestion.proposed.iban string, nullable no Up to 42 characters. Pattern: ^[A-Za-z]{2}[0-9A-Za-z ]+$.
collectiveSuggestion.proposed.bic string, nullable no
collectiveSuggestion.proposed.reverseChargeOverride string no One of: auto, ignore, force.
collectiveSuggestion.proposed.tipHandling string no One of: auto, off, notice, line.
collectiveSuggestion.existingSubVendorId string (uuid), nullable no
ordererName string, nullable no
vendorPrinted object yes
vendorPrinted.name string, nullable no
vendorPrinted.vatId string, nullable no
vendorPrinted.taxNumber string, nullable no
vendorPrinted.street string, nullable no
vendorPrinted.zip string, nullable no
vendorPrinted.city string, nullable no
vendorPrinted.countryCode string, nullable no
vendorPrinted.bankAccounts array of object yes Default: [].
vendorPrinted.bankAccounts[].iban string yes
vendorPrinted.bankAccounts[].bic string, nullable yes
vendorCheck object, nullable no
vendorCheck.subject string yes One of: vendor, sub_vendor.
vendorCheck.subjectId string (uuid) yes
vendorCheck.vendorId string (uuid) yes
vendorCheck.ledByErp boolean yes
vendorCheck.bankFromErp boolean yes
vendorCheck.vendorIbanLast4 string, nullable yes
vendorCheck.iban string yes One of: match, unknown, vendor_without_iban, pending, none_printed.
vendorCheck.vatId string yes One of: match, differs, vendor_without_vat_id, none_printed.
vendorCheck.name string yes One of: match, differs.
lineItems array of object yes Line items with their account coding (the working state of the review).
lineItems[].id string (uuid) yes
lineItems[].position integer yes Minimum 0. Maximum 9007199254740991.
lineItems[].description string yes
lineItems[].itemNo string, nullable no
lineItems[].quantity string, nullable no Pattern: ^-?\d+(\.\d+)?$.
lineItems[].unit string, nullable no
lineItems[].unitLabel string, nullable no
lineItems[].unitPrice string, nullable no Pattern: ^-?\d+(\.\d+)?$.
lineItems[].netAmount string yes Pattern: ^-?\d+(\.\d+)?$.
lineItems[].taxRate string yes Pattern: ^-?\d+(\.\d+)?$.
lineItems[].originalLineItemIds array of string (uuid) yes
lineItems[].isTip boolean no
lineItems[].dimensions object yes
headerDimensions object yes Account coding on header level. The key is the dimension key, the value holds code and label.
originalLineItems array of object yes
originalLineItems[].id string (uuid) yes
originalLineItems[].position integer yes Minimum 0. Maximum 9007199254740991.
originalLineItems[].itemNo string, nullable no
originalLineItems[].description string yes
originalLineItems[].quantity string, nullable no Pattern: ^-?\d+(\.\d+)?$.
originalLineItems[].unit string, nullable no
originalLineItems[].unitPrice string, nullable no Pattern: ^-?\d+(\.\d+)?$.
originalLineItems[].netAmount string, nullable no Pattern: ^-?\d+(\.\d+)?$.
originalLineItems[].taxRate string, nullable no Pattern: ^-?\d+(\.\d+)?$.
originalLineItems[].appliedRule object, nullable no
originalLineItems[].appliedRule.blueprintId string (uuid) yes
originalLineItems[].appliedRule.positionKey string yes
originalLineItems[].appliedRule.groupId string (uuid), nullable yes
originalLineItems[].appliedRule.bookingText string, nullable yes
originalLineItems[].appliedRule.label string yes
validation object yes
validation.valid boolean yes
validation.issues array of object yes
validation.issues[].code string yes
validation.issues[].severity string yes One of: error, warning.
validation.issues[].message string yes
validation.issues[].field string, nullable no
validation.issues[].lineNumber integer, nullable no Minimum 1. Maximum 9007199254740991.
validation.issues[].dimensionKey string, nullable no
validation.issues[].params object, nullable no
fieldConfidences object yes
reviewedFields array of string yes
blueprint object yes
blueprint.applied boolean yes
blueprint.blueprintId string (uuid), nullable no
blueprint.matchedRuleCount integer yes Minimum 0. Maximum 9007199254740991.
blueprint.suggestedLineItemIds array of string (uuid) yes
blueprint.ruleValues array of object yes
blueprint.ruleValues[].lineItemId string (uuid) yes
blueprint.ruleValues[].dimensionKey string yes
blueprint.ruleValues[].code string yes
duplicate object yes
duplicate.state string yes One of: disabled, no_key, clear, dismissed, open.
duplicate.matchKind string, nullable no One of: invoice_number, date_and_amount.
duplicate.key string, nullable no
duplicate.dismissedAt string (date-time), nullable no
duplicate.original object, nullable no
duplicate.original.id string (uuid) yes
duplicate.original.invoiceNumber string, nullable no
duplicate.original.invoiceDate string (date), nullable no
duplicate.original.grossAmount string, nullable no Pattern: ^-?\d+(\.\d+)?$.
duplicate.original.status string yes One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
duplicate.original.vendorName string, nullable no
reversal object yes
reversal.reversalOf object, nullable no
reversal.reversalOf.id string (uuid) yes
reversal.reversalOf.invoiceNumber string, nullable no
reversal.reversedBy object, nullable no
reversal.reversedBy.id string (uuid) yes
reversal.reversedBy.invoiceNumber string, nullable no
supersededAdvice object, nullable yes
supersededAdvice.number string yes
supersededAdvice.sentAt string (date-time) yes
posting object, nullable no
posting.documentNumber string, nullable yes
posting.postedAt string, nullable yes
posting.deviation object, nullable yes
posting.deviation.noticeId string yes
posting.deviation.readAt string, nullable yes
posting.deviation.payload object yes
posting.deviation.payload.documentNumber string yes
posting.deviation.payload.postedAt string (date-time) yes
posting.deviation.payload.accountNotComparable boolean yes
posting.deviation.payload.deviations array of one of object, object yes
deletedAt string (date-time), nullable no
deletedByUserId string, nullable no
deletedByName string, nullable no
deletedFromStatus string, nullable no One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
deleteReason string, nullable no
createdAt string (date-time) yes When fineelik received the document.
updatedAt string (date-time) yes When the invoice was last changed.
Field Type Required Description
items array of object yes History entries, newest first. At most the latest 200 entries are returned.
items[].id string (uuid) yes Id of the entry.
items[].action string yes Kind of change, for example invoice.status_changed or invoice.line_items_replaced.
items[].actorUserId string, nullable yes Id of the user who acted. null when a machine acted.
items[].actorName string, nullable yes Name of the user, if it can still be resolved.
items[].actorApiKeyId string, nullable yes Id of the API key that acted. null when a user acted.
items[].before object, nullable yes State before the change. The keys depend on the action.
items[].after object, nullable yes State after the change. The keys depend on the action.
items[].metadata object, nullable yes Further details. For a decision reported from outside this holds decidedBy, comment and externalRef.
items[].createdAt string (date-time) yes When the change happened.
Field Type Required Description
decision string yes approved or rejected. One of: approved, rejected.
decidedBy string no Name of the person who decided in the leading system (up to 200 characters). fineelik does not know this person as a user, the name is kept as plain text. Up to 200 characters.
comment string no Reason or note (up to 2000 characters). Up to 2000 characters.
externalRef string no Reference of the leading system, for example a workflow id (up to 200 characters). Kept for the history only. Up to 200 characters.
Field Type Required Description
invoiceId string (uuid) yes Id of the invoice.
status string yes Status after the call: approved or rejected. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
applied boolean yes true: the decision was applied now. false: the same decision was already on record and nothing changed.

One event about an invoice.

Field Type Required Description
id string yes Sequence number of the event, as a string. Unique and ascending. Use it as the cursor for the next call and to recognize an event that arrives twice. Pattern: ^\d{1,19}$.
type string yes Kind of event: - invoice.received: the document was accepted (upload, e-mail or hand over from the document management system). - invoice.status_changed: every change of status, with previousStatus. - invoice.export_changed: data relevant for the export changed after review without a change of status, for example the account coding was corrected or the vendor changed. - invoice.processing_failed: processing (preflight, text recognition, extraction, matching) failed after the last automatic attempt, or waits for a missing setting. The status stays, statusReason is <step>_failed: <text>. Intermediate errors before another attempt (<step>_retry) create no event. One of: invoice.received, invoice.status_changed, invoice.export_changed, invoice.processing_failed.
occurredAt string (date-time) yes When the event was created.
invoiceId string (uuid) yes Id of the invoice.
companyId string (uuid) yes Id of the company of the invoice.
companyCode string yes Code of the company.
dmsGuid string, nullable yes GUID of the document in the document management system (for example ELO) when the invoice came from there, otherwise null.
status string yes Status of the invoice after the event. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
previousStatus string, nullable yes Only for invoice.status_changed: the status before. Otherwise null. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
statusReason string, nullable yes Reason for the status after the event, if any.
agreementMatch object, nullable yes Contract block (module “Contracts”) as it is when the event is fetched or delivered, the same as agreementMatch in InvoiceExport. null without the module, without assignment, or when it could not be determined (then do not approve automatically). Confidential contracts: only confidential and result per entry, no number and no amounts. Default: null.
agreementMatch.outcome string yes Result for the whole invoice: ok (fully assigned, within the tolerance, nothing open), deviation, unchecked (an assignment could not be checked, for example without amount), suggested (only a suggestion, or an open suggestion beside the assignment), partial (not every position is assigned, or positions are assigned twice) or none. One of: ok, deviation, unchecked, suggested, partial, none.
agreementMatch.autoApprovalPossible boolean yes true when every rule of the automatic approval holds, so blockers is empty.
agreementMatch.blockers array of string yes Reasons against the automatic approval, as codes in a fixed order: module_not_licensed, company_auto_approve_off, match_failed, outcome_none, outcome_suggested, outcome_partial, outcome_unchecked, outcome_deviation, agreement_not_active, conditions_not_approved, conditions_pending, agreement_auto_approve_off, vendor_mismatch, amount_missing, max_amount_exceeded, first_invoice_of_vendor, bank_account_deviates, bank_account_recently_changed, duplicate_suspected, open_error_findings, credit_note, currency_mismatch, second_invoice_in_period, needs_clearance, order_match_deviation, sample_due. Treat unknown codes as a reason against.
agreementMatch.links array of object yes One entry per effective assignment (automatic, manual or confirmed).
agreementMatch.links[].confidential boolean yes true for a confidential contract. Then every field except result is null.
agreementMatch.links[].agreementId string (uuid), nullable yes Id of the contract in fineelik.
agreementMatch.links[].number string, nullable yes Number of the contract in fineelik.
agreementMatch.links[].externalNumber string, nullable yes Number of the contract at the partner or in the leading system, or null.
agreementMatch.links[].matchSource string, nullable yes auto, suggested (confirmed by a person) or manual. One of: auto, suggested, manual.
agreementMatch.links[].result string yes Result of the check: ok, deviation or unchecked. One of: ok, deviation, unchecked.
agreementMatch.links[].currency string, nullable yes Currency of the contract (ISO 4217).
agreementMatch.links[].expectedAmount string, nullable yes Expected amount for the period of the invoice (net or gross as set in the contract). Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].actualAmount string, nullable yes Actual amount of the invoice or of its assigned positions. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].deviationAmount string, nullable yes Actual minus expected amount (positive above the expected amount). Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].deviationPercent string, nullable yes Deviation in percent of the expected amount, two decimals.
agreementMatch.links[].allowedUpAmount string, nullable yes Allowed deviation upwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].allowedDownAmount string, nullable yes Allowed deviation downwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].externalGuid string, nullable yes Default: null.
Field Type Required Description
items array of one of IntegrationEvent, AgreementIntegrationEvent yes Events in ascending order of id.
nextCursor string yes Id of the last event in this answer, or the after value of the call when nothing was found. Pass it as after in the next call. Pattern: ^\d{1,19}$.
hasMore boolean yes true when more events wait. Call again at once with nextCursor.

One event about a contract managed in ELO. agreement is the state when the event is fetched or delivered (see AgreementEloState), null when the contract no longer exists or the module is not licensed.

Field Type Required Description
id string yes Sequence number of the event, as a string, from the same stream as the invoice events. Pattern: ^\d{1,19}$.
type string yes Kind of event (only for contracts managed in ELO): - agreement.conditions_approved: the matching conditions were approved in fineelik. - agreement.conditions_changed: the conditions changed (in fineelik or by a hand over from ELO), were submitted for approval, rejected or withdrawn; see reason. - agreement.partner_assigned: the partner was assigned to a vendor, or the assignment changed. - agreement.tags_changed: the keywords changed (agreement.tagsText). - agreement.auto_approve_changed: the switch for the automatic approval changed. One of: agreement.conditions_approved, agreement.conditions_changed, agreement.partner_assigned, agreement.tags_changed, agreement.auto_approve_changed.
occurredAt string (date-time) yes
agreementId string (uuid) yes Id of the contract in fineelik.
companyId string (uuid) yes
companyCode string yes
externalSystem string, nullable yes
externalGuid string, nullable yes GUID of the contract in ELO.
status string yes State of the contract in fineelik at the time of the event. One of: draft, in_negotiation, in_approval, approved, signed, active, in_termination, terminated, ended.
reason string, nullable yes Occasion: elo_handover, fineelik_edit, submitted, rejected, withdrawn, partner_mapping or extraction; null for an approval.
agreement all of AgreementEloState yes

State of a contract that is managed in ELO Contract (module “Contracts”), for the leading system. It holds only what ELO has anyway (status, identifiers) and the fields that belong to fineelik: the vendor the partner is assigned to, net or gross, tolerances, automatic approval, object numbers, keywords, match keys and whether the matching conditions are approved in fineelik. No document content, no title and no summary, so the same applies to confidential contracts.

automationReady is true when nothing at the contract speaks against the automatic approval of invoices (status in ELO COMPLETED, conditions approved in fineelik, switch on at the contract and in the company, partner assigned). The rules per invoice (bank account, duplicate, sample, …) come on top and are in agreementMatch of the invoice.

Field Type Required Description
agreementId string (uuid) yes Id of the contract in fineelik.
companyId string (uuid) yes
companyCode string yes
number string yes Number of the contract in fineelik.
externalSystem string yes
externalGuid string yes GUID of the contract in ELO (Sord.guid), in ELO notation.
externalRevision string, nullable yes Revision of the last accepted hand over (as sent in revision).
externalChangedAt string (date-time), nullable yes Time of change in ELO of the last accepted hand over.
status string yes State in fineelik, mapped from the status in ELO (COMPLETED is active). It comes only from ELO. One of: draft, in_negotiation, in_approval, approved, signed, active, in_termination, terminated, ended.
eloStatus string, nullable yes Status key in ELO as sent, for example COMPLETED.
confidential boolean yes
partner object, nullable yes Contract partner (first PARTNER of the hand over) and the vendor it is assigned to, or null without partner.
partner.externalKey string yes
partner.name string, nullable yes
partner.assigned boolean yes
partner.vendorId string (uuid), nullable yes
partner.vendorName string, nullable yes
partner.erpVendorNumber string, nullable yes
partner.source string, nullable yes One of: auto, user.
partner.unresolvedReason string, nullable yes One of: none, ambiguous.
amountBasis string yes One of: net, gross.
tolerance object yes
tolerance.upPercent string, nullable yes Pattern: ^\d{1,3}(\.\d{1,2})?$.
tolerance.downPercent string, nullable yes Pattern: ^\d{1,3}(\.\d{1,2})?$.
tolerance.upAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
tolerance.downAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
autoApprove boolean yes
noPayments boolean yes
tags array of string yes Confirmed keywords of the contract (fineelik list), alphabetical.
tagsText string yes The same keywords as one text separated by ; , for the text field in ELO.
matchKeys array of string yes Identifiers fineelik uses to assign invoices (number at the partner, customer number, object numbers).
responsible object, nullable yes Responsible person in fineelik with e-mail, or null.
responsible.userId string yes
responsible.email string, nullable yes
secondResponsible object, nullable yes
secondResponsible.userId string yes
secondResponsible.email string, nullable yes
paymentLines array of object yes Payment lines with the fields that belong to fineelik, keyed by externalKey (the lineKey of the hand over, otherwise pos:<n>). removed lines were removed in ELO; they stay in fineelik because invoices refer to them.
paymentLines[].externalKey string, nullable yes
paymentLines[].sequence integer yes Minimum -9007199254740991. Maximum 9007199254740991.
paymentLines[].removed boolean yes
paymentLines[].kind string yes One of: fixed, variable.
paymentLines[].objectNumber string, nullable yes
paymentLines[].tolerance object yes
paymentLines[].tolerance.upPercent string, nullable yes Pattern: ^\d{1,3}(\.\d{1,2})?$.
paymentLines[].tolerance.downPercent string, nullable yes Pattern: ^\d{1,3}(\.\d{1,2})?$.
paymentLines[].tolerance.upAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
paymentLines[].tolerance.downAmount string, nullable yes Pattern: ^-?\d+(\.\d{1,2})?$.
conditions object yes Approval of the matching conditions in fineelik. Every change of a condition (also one from ELO: partner, term, currency, payments) needs a new approval in fineelik.
conditions.approved boolean yes
conditions.pending boolean yes
conditions.everApproved boolean yes
conditions.approvedAt string (date-time), nullable yes
conditions.fingerprint string yes
conditions.approvedFingerprint string, nullable yes
automationReady boolean yes See the description of the schema.
automationBlockers array of string yes Reasons at the contract against the automatic approval: elo_not_active, conditions_not_approved, conditions_pending, auto_approve_off, company_auto_approve_off, partner_unassigned. Treat unknown codes as a reason against.
openPoints array of string yes Open points for people: partner_unassigned, type_unknown (mask without contract type), conditions_not_approved, payments_incomplete (a payment without amount or cycle), quota_reached (the contract quota of the instance is reached and this contract does not take up a place yet, so its conditions cannot be submitted).

Hand over of a contract from ELO Contract. Field names and list keys as in ELO; unknown fields of an aspect are stored without loss. Money as decimal strings with at most two decimals.

Field Type Required Description
companyId string (uuid) no Company in fineelik. A key is bound to one company; then leave it out (another value answers 404).
revision string yes Revision of the contract in ELO, for example Sord.tStamp. Kept in the history. Up to 200 characters.
changedAt string (date-time) yes Time of the change in ELO. A state older than the stored one is not applied (outcome stale).
maskKey string yes Mask of the contract in ELO (GENERAL_CONTRACT, PARTNER_CONTRACT, SERVICE_CONTRACT, LEASE_CONTRACT, SALES_CONTRACT or a mask of the customer). It selects the contract type in fineelik; an unknown mask falls back to GENERAL_CONTRACT and is reported. Up to 64 characters.
name string yes Short name of the contract (Sord.name), the title in fineelik. Up to 300 characters.
CONTRACT_DETAILS object yes Aspect ELO_CONTRACT.CONTRACT_DETAILS with the ELO field names. CONTRACT_STATUS is required. Fields of type USER are objects with email (fineelik maps the person by e-mail) and name.
CONTRACT_DETAILS.CONTRACT_STATUS string yes Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_NO string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_EXTERNAL_NO string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_TYPE string, nullable no Up to 200 characters.
CONTRACT_DETAILS.CONTRACT_TYPE_KEY string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_PHASE string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CURRENCY string, nullable no Up to 3 characters.
CONTRACT_DETAILS.BUSINESS_RELATION string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_RISK string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_DEPARTMENT string, nullable no Up to 200 characters.
CONTRACT_DETAILS.DESCRIPTION string, nullable no Up to 10000 characters.
CONTRACT_DETAILS.CONTRACT_RELATION string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_RESPONSIBLE object, nullable no
CONTRACT_DETAILS.CONTRACT_RESPONSIBLE.name string, nullable no Up to 200 characters.
CONTRACT_DETAILS.CONTRACT_RESPONSIBLE.email string (email), nullable no Up to 320 characters.
CONTRACT_DETAILS.CONTRACT_PROCUREMENT object, nullable no
CONTRACT_DETAILS.CONTRACT_PROCUREMENT.name string, nullable no Up to 200 characters.
CONTRACT_DETAILS.CONTRACT_PROCUREMENT.email string (email), nullable no Up to 320 characters.
CONTRACT_DETAILS.COUNTRY string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_APPLICABLE_LAW string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_PLACE_OF_EXECUTION string, nullable no Up to 100 characters.
CONTRACT_DETAILS.CONTRACT_LANGUAGE string, nullable no Up to 100 characters.
CONTRACT_DETAILS.ORGANIZATION string, nullable no Up to 200 characters.
CONTRACT_PERIOD object, nullable no Aspect ELO_CONTRACT.CONTRACT_PERIOD with the ELO field names.
CONTRACT_PERIOD.CONTRACT_START string (date), nullable no
CONTRACT_PERIOD.CONTRACT_END string (date), nullable no
CONTRACT_PERIOD.SIGNING_DATE string (date), nullable no
CONTRACT_PERIOD.CONTRACT_DURATION integer, nullable no Minimum 0. Maximum 1200.
CONTRACT_PERIOD.CONTRACT_DURATION_UNIT string, nullable no Up to 100 characters.
CONTRACT_PERIOD.CONTRACT_DURATION_TYPE string, nullable no Up to 100 characters.
CONTRACT_PERIOD.CONTRACT_EXTENSION_TYPE string, nullable no Up to 100 characters.
CONTRACT_PERIOD.EXTENSION_BY_COUNT integer, nullable no Minimum 0. Maximum 1200.
CONTRACT_PERIOD.EXTENSION_UNIT string, nullable no Up to 100 characters.
CONTRACT_PERIOD.CONTRACT_END_AFTER_EXTENSION string (date), nullable no
CONTRACT_PERIOD.ORIGINAL_CONTRACT_END string (date), nullable no
CONTRACT_PERIOD.NEXT_CALC_DATE string (date), nullable no
CONTRACT_PERIOD.CONTRACT_AUTO_CALCULATION integer, nullable no Minimum -9007199254740991. Maximum 9007199254740991.
CONTRACT_TERMINATION object, nullable no Aspect ELO_CONTRACT.CONTRACT_TERMINATION with the ELO field names.
CONTRACT_TERMINATION.TERMINATION_PERIOD integer, nullable no Minimum 0. Maximum 1200.
CONTRACT_TERMINATION.TERMINATION_PERIOD_UNIT string, nullable no Up to 100 characters.
CONTRACT_TERMINATION.TERMINATION_EFFECTIVE_FROM string, nullable no Up to 100 characters.
CONTRACT_TERMINATION.TERMINATION_TYPE string, nullable no Up to 100 characters.
CONTRACT_TERMINATION.DEADLINE_TYPE string, nullable no Up to 100 characters.
CONTRACT_TERMINATION.TERMINATION_DAY_OF_MONTH integer, nullable no Minimum 1. Maximum 31.
CONTRACT_TERMINATION.TERMINATION_MANUAL_END integer, nullable no Minimum -9007199254740991. Maximum 9007199254740991.
CONTRACT_TERMINATION.TERMINATION_LAST_DATE string (date), nullable no
CONTRACT_TERMINATION.POSSIBLE_EFFECTIVE_DATE string (date), nullable no
CONTRACT_TERMINATION.TERMINATION_DATE string (date), nullable no
CONTRACT_TERMINATION.TERMINATION_EFFECTIVE_DATE string (date), nullable no
CONTRACT_TERMINATION.TERMINATION_CONTRACT_TYPE string, nullable no Up to 100 characters.
CONTRACT_TERMINATION.TERMINATION_REASON string, nullable no Up to 2000 characters.
CONTRACT_TERMINATION.TERMINATION_BY object, nullable no
CONTRACT_TERMINATION.TERMINATION_BY.name string, nullable no Up to 200 characters.
CONTRACT_TERMINATION.TERMINATION_BY.email string (email), nullable no Up to 320 characters.
CONTRACT_TERMINATION.EXTRAORDINARY_PERIOD integer, nullable no Minimum 0. Maximum 1200.
CONTRACT_TERMINATION.EXTRAORDINARY_PERIOD_UNIT string, nullable no Up to 100 characters.
CONTRACT_TERMINATION.EXTRAORDINARY_EFFECTIVE_FROM string, nullable no Up to 100 characters.
CONTRACT_TERMINATION.EXTRAORDINARY_CONDITION string, nullable no Up to 2000 characters.
CONTRACT_TERMINATION.EXTRAORDINARY_LAST_DATE string (date), nullable no
CONTRACT_TERMINATION.EXTRAORDINARY_EFFECTIVE_DATE string (date), nullable no
CONTRACT_VALUE object, nullable no Aspect ELO_CONTRACT.CONTRACT_VALUE with the ELO field names.
CONTRACT_VALUE.CURRENCY string, nullable no Up to 3 characters.
CONTRACT_VALUE.CONTRACT_VALUE string, nullable no Pattern: ^-?\d+(\.\d{1,2})?$.
CONTRACT_VALUE.SUM_PERIODIC_PAYMENTS string, nullable no Pattern: ^-?\d+(\.\d{1,2})?$.
CONTRACT_VALUE.CONTRACT_END string (date), nullable no
CONTRACT_STATUS_INFO object, nullable no Aspect ELO_CONTRACT.CONTRACT_STATUS_INFO. Stored, not evaluated.
CONTRACT_STATUS_INFO.MESSAGE string, nullable no Up to 2000 characters.
CONTRACT_STATUS_INFO.SENDER object, nullable no
CONTRACT_STATUS_INFO.SENDER.name string, nullable no Up to 200 characters.
CONTRACT_STATUS_INFO.SENDER.email string (email), nullable no Up to 320 characters.
PARTNER array of object no Aspect ELO_CONTRACT.PARTNER, 0 to n entries. The first one is the contract partner. PARTNER is the GUID of the contact in ELO and the key of the remembered assignment to a vendor. Send name, vatId, taxNumber, creditorNumber and ibans of the contact when you have them: fineelik assigns the vendor automatically by the remembered assignment, the creditor number, the VAT or tax number, the IBAN and last the exact name, and never guesses between several hits. Default: [].
PARTNER[].PARTNER string yes Up to 200 characters.
PARTNER[].CONTACT_PERSON string, nullable no Up to 200 characters.
PARTNER[].name string, nullable no Up to 300 characters.
PARTNER[].vatId string, nullable no Up to 40 characters.
PARTNER[].taxNumber string, nullable no Up to 40 characters.
PARTNER[].creditorNumber string, nullable no Up to 60 characters.
PARTNER[].ibans array of string no Default: [].
PAYMENTS array of object no Aspect ELO_CONTRACT.PAYMENTS, 0 to n entries (CYCLE from ELO_COMMON.TIME_INTERVAL, SINGLE_AMOUNT as a decimal string). Send a stable lineKey per line when you have one, otherwise fineelik keys the lines by position. With DATE_TYPE RELATIVE send the resolved PAYMENT_START and PAYMENT_END. A line without amount or cycle is stored but not matched (warning payment_incomplete). Default: [].
PAYMENTS[].lineKey string, nullable no Up to 100 characters.
PAYMENTS[].PAYMENT_DESCRIPTION string, nullable no Up to 300 characters.
PAYMENTS[].CYCLE string, nullable no Up to 100 characters.
PAYMENTS[].SINGLE_AMOUNT string, nullable no Pattern: ^-?\d+(\.\d{1,2})?$.
PAYMENTS[].PAYMENT_START string (date), nullable no
PAYMENTS[].PAYMENT_END string (date), nullable no
PAYMENTS[].PAYMENT_SUM string, nullable no Pattern: ^-?\d+(\.\d{1,2})?$.
PAYMENTS[].PAYMENT_COUNT integer, nullable no Minimum 0. Maximum 9007199254740991.
PAYMENTS[].DATE_TYPE string, nullable no Up to 100 characters.
PAYMENTS[].REFERENCE_START_KEY string, nullable no Up to 100 characters.
PAYMENTS[].REFERENCE_END_KEY string, nullable no Up to 100 characters.
Field Type Required Description
outcome string yes created, updated, unchanged (the same payload as last time: nothing changed, nothing triggered) or stale (older than the stored state: nothing changed). One of: created, updated, unchanged, stale.
conditionsChanged boolean yes true when the matching conditions changed: the automatic approval rests until the conditions are approved again in fineelik.
approvalWithdrawn boolean yes true when a running approval of the conditions in fineelik was withdrawn because the conditions changed. It has to be submitted again.
warnings array of object yes What was accepted but could not be mapped completely: unknown_value, payment_incomplete, currency_conflict, type_unknown, extra_partners, partner_unassigned, user_unmatched, each with the ELO field and value.
warnings[].code string yes One of: unknown_value, payment_incomplete, currency_conflict, type_unknown, extra_partners, partner_unassigned, user_unmatched.
warnings[].field string, nullable yes
warnings[].value string, nullable yes
state AgreementEloState yes
Field Type Required Description
agreementId string (uuid) yes
documentId string (uuid) yes
created boolean yes
Field Type Required Description
invoiceId string (uuid) yes Id of the invoice in fineelik.
status string yes Status of the invoice. See “Invoice status” in the API introduction. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
Field Type Required Description
invoiceId string (uuid) no
Field Type Required Description
invoiceId string (uuid) yes Id of the invoice in fineelik. Fetch the file with getInvoicePdf.
companyId string (uuid) yes Company of the invoice.
companyCode string yes Code of the company.
fileName string yes Original file name, for the name of the document in the document management system.
contentType string yes application/pdf, or application/xml for an e-invoice.
byteSize integer, nullable yes Size of the file in bytes, if known. Minimum 0. Maximum 9007199254740991.
captureChannel string yes How the document arrived in fineelik: upload (web app and mobile app), email (mailbox address) or api. One of: upload, email, api.
createdAt string (date-time) yes When the document arrived in fineelik.
attempt integer yes Which fetch of this document this is (1 = first). Minimum 0. Maximum 9007199254740991.
Field Type Required Description
item object, nullable yes The next document for the document management system, or null if none is due.
item.invoiceId string (uuid) yes
item.companyId string (uuid) yes
item.companyCode string yes
item.fileName string yes
item.contentType string yes
item.byteSize integer, nullable yes Minimum 0. Maximum 9007199254740991.
item.captureChannel string yes One of: upload, email, api.
item.createdAt string (date-time) yes
item.attempt integer yes Minimum 0. Maximum 9007199254740991.

Type: any of object, object

Field Type Required Description
invoiceId string (uuid) yes Id of the invoice.
result string yes created (GUID set), repeated (the same GUID was already set), other_document (the invoice already belongs to another document, the reported one is a copy) or failed (reason stored, fineelik offers the document again later). One of: created, repeated, other_document, failed.
status string yes Status of the invoice. See “Invoice status” in the API introduction. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.

Neutral export state of one invoice for the leading system. It contains no field names or ids of a specific system; mapping to the target system is the job of the receiver.

Payment method. paymentMethod is null when none is set. erpCode is the payment form code in the ERP (Business Central Payment_Method_Code, Code[10]), stored on the payment method of the company. It is null while the invoice is before or in review (captured, extracted, review_required), when the payment method has no code, and when source is company_default or null. In these cases the ERP keeps the payment form of the vendor, and the default of the company overwrites nothing that the ERP keeps differently. The receiver writes only codes and never clears an existing value.

Collective vendors. A collective vendor (a catch-all account such as “Various vendors EU”) is an ordinary vendor account in the leading system. In fineelik it holds one-time vendors as sub-vendors. Their name, VAT id, address, e-mail and bank details live only in fineelik. The export always names the collective vendor under vendor, because only that one is known to the leading system. There is no block for the sub-vendor.

Booking lines and document positions. lines are the booking lines as fineelik codes them (working state after template and review). One booking line can combine several positions of the document. documentLines are the positions as printed on the document: the unchangeable state of the extraction, in ascending order of position, including positions that belong to no booking line. lines[].documentPositions lists the position values of the document positions that a booking line combines (one each right after extraction). It is empty when the line does not come from a document position, for example when it was added in review. Documents without extracted positions (for example imported open items or invoices entered by hand) have documentLines: [] and documentPositions: [] in every line. The export always shows the current state: a new grouping in review changes only documentPositions; “process again” discards the document positions and reads them anew; reopening leaves them unchanged.

Service period and deferral. servicePeriodStart and servicePeriodEnd are the service period according to the document (YYYY-MM-DD or null). A single service date appears as from = to. If the document names no period, both are null; the invoice date is never used as a substitute. The end is never before the start. The deferral of a line with a deferral code (lines[].accounting.deferral_code) starts at servicePeriodStart; the number of periods comes from the template in the ERP.

Field Type Required Description
invoiceId string (uuid) yes Id of the invoice.
revision string yes Opaque fingerprint of the whole export. It changes with anything in the export, also with status, reason, review note (reviewedAt, reviewedBy), vendor and master data of the company.
dataRevision string yes Opaque fingerprint of only those invoice data that the receiver writes into its own invoice: company.code, documentType, invoiceNumber, invoiceDate, deliveryDate, servicePeriodStart, servicePeriodEnd, dueDate, currency, netAmount, taxAmount, grossAmount, homeAmounts (when present), taxLines, paymentTerms, accounting (header), lines with their accounting (also deferral_code) and documentPositions, documentLines, the explicit vendor assignment vendor.id (or null) and paymentMethod.erpCode, only when it is set. NOT covered: the other vendor master data under vendor, company.id, company.name, company.vatId, invoiceId, dmsGuid, status, statusReason and the review note. Write invoice data only when dataRevision is new. Then a pure status change, renaming a vendor or linking it to the ERP for the first time overwrites no correction made in the leading system. Take the vendor account (vendor.erpVendorNumber) over separately, on invoice.export_changed and only where it is still missing. A change of the assigned vendor (A to B) changes dataRevision.
dmsGuid string, nullable yes GUID of the document in the document management system, or null.
status string yes Status of the invoice. See “Invoice status” in the API introduction. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
statusReason string, nullable yes Reason for the status, for example approval_external.
company object yes The company the invoice belongs to.
company.id string (uuid) yes Id of the company.
company.code string yes Code of the company. The receiver uses it to select its own unit.
company.name string yes Name of the company.
company.vatId string, nullable yes VAT id of the company, if known.
vendor object, nullable yes The matched vendor, or null when none is assigned. For invoices of a sub-vendor this is the collective vendor.
vendor.id string (uuid) yes Id of the vendor in fineelik.
vendor.name string yes Name of the vendor.
vendor.vatId string, nullable yes VAT id of the vendor, if known.
vendor.countryCode string, nullable yes Country code of the vendor, if known.
vendor.erpVendorNumber string, nullable yes Vendor account number in the ERP (Business Central “No.”), if linked.
vendor.erpExternalId string, nullable yes Id in the ERP (Business Central SystemId), if linked.
documentType string yes invoice or credit_note. One of: invoice, credit_note.
invoiceNumber string, nullable yes Invoice number as printed on the document.
invoiceDate string (date), nullable yes Invoice date.
deliveryDate string (date), nullable yes Delivery date.
servicePeriodStart string (date), nullable yes Start of the service period according to the document, or null.
servicePeriodEnd string (date), nullable yes End of the service period according to the document, or null.
dueDate string (date), nullable yes Due date.
currency string, nullable yes Currency of the document (ISO 4217). Pattern: ^[A-Z]{3}$.
netAmount string, nullable yes Net amount as a decimal string. Pattern: ^-?\d+(\.\d+)?$.
taxAmount string, nullable yes Tax amount as a decimal string. Pattern: ^-?\d+(\.\d+)?$.
grossAmount string, nullable yes Gross amount as a decimal string. Pattern: ^-?\d+(\.\d+)?$.
homeAmounts object, nullable yes Amounts in the home currency of the company at the rate of the invoice date. null for invoices in the home currency and while no rate is available (for example the invoice date or gross amount is missing, the date lies in the future, or the currency has no ECB rate).
homeAmounts.currency string yes Home currency of the company. Pattern: ^[A-Z]{3}$.
homeAmounts.exchangeRate string yes Units of the invoice currency per one unit of the home currency, as quoted by the ECB. For 1 EUR = 1.0832 USD this is "1.0832". The home amount is the amount divided by the rate, rounded commercially to the decimals of the home currency. Pattern: ^-?\d+(\.\d+)?$.
homeAmounts.rateDate string (date) yes Date of the rate.
homeAmounts.source string yes ECB for a rate of the European Central Bank, fixed for a fixed rate. One of: ECB, fixed.
homeAmounts.netAmount string, nullable yes Net amount in the home currency, or null. Pattern: ^-?\d+(\.\d+)?$.
homeAmounts.grossAmount string yes Gross amount in the home currency. Pattern: ^-?\d+(\.\d+)?$.
taxLines array of object yes Tax by tax rate.
taxLines[].taxRate string yes Tax rate in percent. Pattern: ^-?\d+(\.\d+)?$.
taxLines[].netAmount string yes Net amount for this rate. Pattern: ^-?\d+(\.\d+)?$.
taxLines[].taxAmount string yes Tax amount for this rate. Pattern: ^-?\d+(\.\d+)?$.
paymentTerms array of object yes Payment terms of the invoice.
paymentTerms[].rank integer yes 1 is the term that fineelik applies (the best valid one). Minimum -9007199254740991. Maximum 9007199254740991.
paymentTerms[].dueDate string (date), nullable yes Due date of this term, or null.
paymentTerms[].days integer, nullable yes Number of days of this term, or null. Minimum -9007199254740991. Maximum 9007199254740991.
paymentTerms[].discountPercent string, nullable yes Cash discount in percent, or null. Pattern: ^-?\d+(\.\d+)?$.
paymentTerms[].discountAmount string, nullable yes Cash discount amount, or null. Pattern: ^-?\d+(\.\d+)?$.
paymentMethod object, nullable yes Payment method of the invoice, or null when none is set. See the notes of this schema.
paymentMethod.kind string yes Kind of payment method: bank_transfer, direct_debit, credit_card, debit_card, online or cash. One of: cash, credit_card, bank_transfer, private_outlay, direct_debit, debit_card, online.
paymentMethod.label string yes Name of the payment method.
paymentMethod.erpCode string, nullable yes Payment form code in the ERP (for example Business Central Payment_Method_Code), or null. See the notes of this schema.
paymentMethod.source string, nullable yes Where the payment method comes from: extraction, vendor_default, company_default, manual or null. One of: extraction, vendor_default, company_default, manual.
accounting object yes Account coding on header level (for example the business posting groups) as dimensions. The key comes from the field catalog of the ERP adapter, the value holds code and label.
lines array of object yes Booking lines with their account coding. See the notes of this schema for how they relate to documentLines.
lines[].lineNumber integer yes Number of the booking line. Minimum -9007199254740991. Maximum 9007199254740991.
lines[].documentPositions array of integer yes The position values of the document positions that this booking line combines. Empty when the line does not come from a document position.
lines[].description string yes Description of the line.
lines[].quantity string, nullable yes Quantity as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
lines[].unit string, nullable yes Code of a unit of the company (master data type unitsOfMeasure), or null when no unit is assigned. With Business Central it is the Business Central code (Code[10]). Without an ERP the standard units carry UN/ECE codes (Recommendation 20, package and unit from Recommendation 21 with a leading X), for example H87 piece, HUR hour, LS lump sum, KGM kilogram; units created by hand keep their own code. The unit as printed is in documentLines[].unit. Documents from before the switch of 28 September 2026 can still carry the printed text here until someone picks the unit in review.
lines[].unitPrice string, nullable yes Unit price as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
lines[].netAmount string, nullable yes Net amount as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
lines[].taxRate string, nullable yes Tax rate in percent as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
lines[].taxAmount string, nullable yes Tax amount as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
lines[].grossAmount string, nullable yes Gross amount as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
lines[].accounting object yes Account coding of the line as dimensions. The key comes from the field catalog of the ERP adapter (for example general_ledger_account, cost_center, cost_bearer, general_product_posting_group, vat_product_posting_group, general_business_posting_group, vat_business_posting_group, booking_text, deferral_code and further dimensions), the value holds code and label. Lines without deferral have no deferral_code key.
documentLines array of object yes The positions as printed on the document (unchangeable state of the extraction), in ascending order of position.
documentLines[].position integer yes Position on the document. Minimum -9007199254740991. Maximum 9007199254740991.
documentLines[].description string yes Description as printed.
documentLines[].quantity string, nullable yes Quantity as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
documentLines[].unit string, nullable yes Unit as printed. This is text, not a code.
documentLines[].unitPrice string, nullable yes Unit price in full precision as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
documentLines[].netAmount string, nullable yes Net amount with two decimals as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
documentLines[].taxRate string, nullable yes Tax rate with two decimals as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$.
reviewedAt string (date-time), nullable yes When accounting finished the review in fineelik, or null.
reviewedBy string, nullable yes Who finished the review in fineelik, or null.
agreementMatch object, nullable yes Contract block (module “Contracts”). null without the module or when the invoice is not assigned to a contract. It carries the result of the contract check, one entry per effective assignment and whether fineelik would approve the invoice automatically (autoApprovalPossible) with the reasons against it (blockers), by the same rules as the automatic approval inside fineelik, without changing anything. A leading system that approves on its own (for example ELO) can skip its approval step when autoApprovalPossible is true. Confidential contracts: a machine is never a named viewer. For a confidential contract the entry holds only confidential and result; number, external number and all amounts of the contract are null. Default: null.
agreementMatch.outcome string yes Result for the whole invoice: ok (fully assigned, within the tolerance, nothing open), deviation, unchecked (an assignment could not be checked, for example without amount), suggested (only a suggestion, or an open suggestion beside the assignment), partial (not every position is assigned, or positions are assigned twice) or none. One of: ok, deviation, unchecked, suggested, partial, none.
agreementMatch.autoApprovalPossible boolean yes true when every rule of the automatic approval holds, so blockers is empty.
agreementMatch.blockers array of string yes Reasons against the automatic approval, as codes in a fixed order: module_not_licensed, company_auto_approve_off, match_failed, outcome_none, outcome_suggested, outcome_partial, outcome_unchecked, outcome_deviation, agreement_not_active, conditions_not_approved, conditions_pending, agreement_auto_approve_off, vendor_mismatch, amount_missing, max_amount_exceeded, first_invoice_of_vendor, bank_account_deviates, bank_account_recently_changed, duplicate_suspected, open_error_findings, credit_note, currency_mismatch, second_invoice_in_period, needs_clearance, order_match_deviation, sample_due. Treat unknown codes as a reason against.
agreementMatch.links array of object yes One entry per effective assignment (automatic, manual or confirmed).
agreementMatch.links[].confidential boolean yes true for a confidential contract. Then every field except result is null.
agreementMatch.links[].agreementId string (uuid), nullable yes Id of the contract in fineelik.
agreementMatch.links[].number string, nullable yes Number of the contract in fineelik.
agreementMatch.links[].externalNumber string, nullable yes Number of the contract at the partner or in the leading system, or null.
agreementMatch.links[].matchSource string, nullable yes auto, suggested (confirmed by a person) or manual. One of: auto, suggested, manual.
agreementMatch.links[].result string yes Result of the check: ok, deviation or unchecked. One of: ok, deviation, unchecked.
agreementMatch.links[].currency string, nullable yes Currency of the contract (ISO 4217).
agreementMatch.links[].expectedAmount string, nullable yes Expected amount for the period of the invoice (net or gross as set in the contract). Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].actualAmount string, nullable yes Actual amount of the invoice or of its assigned positions. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].deviationAmount string, nullable yes Actual minus expected amount (positive above the expected amount). Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].deviationPercent string, nullable yes Deviation in percent of the expected amount, two decimals.
agreementMatch.links[].allowedUpAmount string, nullable yes Allowed deviation upwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].allowedDownAmount string, nullable yes Allowed deviation downwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].externalGuid string, nullable yes Default: null.
Field Type Required Description
id string (uuid) yes Id of the webhook.
url string yes Target address. Values of query parameters and a fragment are masked as ***.
urlHasSecret boolean yes true when the address contains hidden values (query parameters or a fragment). To change the address, enter it completely again.
description string, nullable yes Free text, up to 200 characters.
eventTypes array of string yes The event types that are delivered.
companyId string (uuid), nullable yes The company the webhook is limited to. null means all companies the creator can see.
companyName string, nullable yes Name of that company, or null.
active boolean yes false while the webhook is paused.
createdAt string (date-time) yes When the webhook was created.
cursor string yes Number of the last event up to which everything that matches was delivered. Pattern: ^\d{1,19}$.
pendingEvents integer yes Number of events that still wait for delivery (with the current access of the creator). Minimum 0. Maximum 9007199254740991.
lastDeliveryAt string (date-time), nullable yes Time of the last delivery attempt, or null.
lastDeliveryOk boolean, nullable yes Whether the last attempt succeeded, or null.
lastError string, nullable yes Error of the last failed attempt (the address is masked), or null. webhook.creator_no_access when the creator has no access any more.
failingSince string (date-time), nullable yes Since when deliveries fail, or null while they work.
Field Type Required Description
items array of Webhook yes The webhooks.
Field Type Required Description
url string (uri) yes Target address. https only, no credentials in the address, up to 500 characters. A token in the query part is allowed (ELO Flows) and appears only masked in answers. Up to 500 characters.
description string, nullable no Free text, up to 200 characters. Up to 200 characters.
eventTypes array of string yes At least one of invoice.received, invoice.status_changed, invoice.export_changed, invoice.processing_failed.
companyId string (uuid), nullable no Limit the webhook to one company (it must be within your access). Without it, all companies you can see at this moment.
secret string no Optional own secret (24 to 200 characters), for example the one entered in ELO Flows. Without it, fineelik generates one. Up to 200 characters.
Field Type Required Description
subscription Webhook yes
secret string yes The signing secret. It appears only in this answer and in the answer to renewing, and never again.

Fields to change. At least one field is required.

Field Type Required Description
url string (uri) no New target address, always complete. An address that contains *** is refused with 400 webhook.url_masked. Up to 500 characters.
description string, nullable no Free text, up to 200 characters. null clears it. Up to 200 characters.
eventTypes array of string no The event types to deliver, at least one.
companyId string (uuid), nullable no Limit to one company, or null for all companies you can see.
active boolean no false pauses the webhook, true resumes it.
Field Type Required Description
secret string no Optional own secret (24 to 200 characters). Without it, fineelik generates a new one. Up to 200 characters.
Field Type Required Description
secret string yes The new signing secret. It appears only in this answer. The old one is invalid now.
Field Type Required Description
ok boolean yes true when the target answered with a 2xx status.
statusCode integer, nullable yes HTTP status of the answer, or null when there was none. Minimum -9007199254740991. Maximum 9007199254740991.
error string, nullable yes Error text (the address is masked), or null.
durationMs integer yes Duration of the call in milliseconds. Minimum 0. Maximum 9007199254740991.

One delivery attempt in the log.

Field Type Required Description
id string (uuid) yes Id of the delivery attempt. The same value is sent in the header X-Fineelik-Delivery.
eventId string, nullable yes Number of the event, or null for a test call. Pattern: ^\d{1,19}$.
eventType string yes Type of the event (ping for a test call).
invoiceId string (uuid), nullable yes Id of the invoice, or null for a test call.
attemptedAt string (date-time) yes When the attempt was made.
statusCode integer, nullable yes HTTP status of the answer, or null when there was none. Minimum -9007199254740991. Maximum 9007199254740991.
ok boolean yes true when the target answered with a 2xx status.
error string, nullable yes Error text (the address is masked), or null.
durationMs integer yes Duration of the call in milliseconds. Minimum 0. Maximum 9007199254740991.
Field Type Required Description
items array of WebhookDelivery yes Delivery attempts, newest first.
total integer yes Number of all entries, for paging. Minimum 0. Maximum 9007199254740991.

The JSON body of a webhook delivery. It has the same shape as one entry of listIntegrationEvents. The only addition is the type ping, which appears in test calls (testWebhook) and means nothing: acknowledge unknown types with 2xx and ignore them.

A test call uses type ping, id "0", the invoice id 00000000-0000-0000-0000-000000000000 and the company of the webhook (the same zero UUID without a fixed company). It changes neither the cursor nor the failure count and appears in the delivery log.

Headers of the delivery

  • X-Fineelik-Signature: t=<unix seconds>,v1=<hex> (signature with a timestamp, recommended).
  • X-Hub-Signature: sha256=<hex> (WebSub format, checked by ELO Flows itself).
  • X-Fineelik-Event: the event type (ping for a test call).
  • X-Fineelik-Delivery: id of this delivery attempt (it appears in the delivery log).
  • User-Agent: fineelik-webhooks/1.
  • Content-Type: application/json.

Verifying the signature. fineelik sends both signatures with the same secret; check one of them. The key is the secret exactly as shown or given, including whsec_ if present (UTF-8). body is the raw request body, byte for byte and before any JSON parsing. Compare in constant time.

  • X-Fineelik-Signature: v1 is the hex HMAC-SHA256 of <t>.<body>, where t is the value from the header. Reject timestamps that are more than 5 minutes away from your own clock. This guards against replay.
  • X-Hub-Signature: sha256= followed by the hex HMAC-SHA256 of <body>, without a timestamp. Against replay use the event number id, which a receiver evaluates for “at least once” anyway.

Test vector: secret whsec_testgeheimnis, t = 1700000000 and body {"id":"42","type":"invoice.status_changed"} give v1=d5f4a33b0c6510fdb99e15e5aa059c51cea8869e2fe7407b161a3e4c1d58f7df and X-Hub-Signature: sha256=21e78171381c266463b9c9ad85f8d0a92d55f7480ce503feb72ed982db8239c4.

Field Type Required Description
id string yes Sequence number of the event, as a string. Unique and ascending. Use it as the cursor for the next call and to recognize an event that arrives twice. Pattern: ^\d{1,19}$.
type string yes Kind of event, see IntegrationEvent. ping appears only in test calls and carries no data. Events about contracts managed in ELO (agreement.*) arrive in the form AgreementIntegrationEvent. Acknowledge and ignore unknown types. One of: invoice.received, invoice.status_changed, invoice.export_changed, invoice.processing_failed, ping.
occurredAt string (date-time) yes When the event was created.
invoiceId string (uuid) yes Id of the invoice.
companyId string (uuid) yes Id of the company of the invoice.
companyCode string yes Code of the company.
dmsGuid string, nullable yes GUID of the document in the document management system (for example ELO) when the invoice came from there, otherwise null.
status string yes Status of the invoice after the event. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
previousStatus string, nullable yes Only for invoice.status_changed: the status before. Otherwise null. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted.
statusReason string, nullable yes Reason for the status after the event, if any.
agreementMatch object, nullable yes Contract block (module “Contracts”) as it is when the event is fetched or delivered, the same as agreementMatch in InvoiceExport. null without the module, without assignment, or when it could not be determined (then do not approve automatically). Confidential contracts: only confidential and result per entry, no number and no amounts. Default: null.
agreementMatch.outcome string yes Result for the whole invoice: ok (fully assigned, within the tolerance, nothing open), deviation, unchecked (an assignment could not be checked, for example without amount), suggested (only a suggestion, or an open suggestion beside the assignment), partial (not every position is assigned, or positions are assigned twice) or none. One of: ok, deviation, unchecked, suggested, partial, none.
agreementMatch.autoApprovalPossible boolean yes true when every rule of the automatic approval holds, so blockers is empty.
agreementMatch.blockers array of string yes Reasons against the automatic approval, as codes in a fixed order: module_not_licensed, company_auto_approve_off, match_failed, outcome_none, outcome_suggested, outcome_partial, outcome_unchecked, outcome_deviation, agreement_not_active, conditions_not_approved, conditions_pending, agreement_auto_approve_off, vendor_mismatch, amount_missing, max_amount_exceeded, first_invoice_of_vendor, bank_account_deviates, bank_account_recently_changed, duplicate_suspected, open_error_findings, credit_note, currency_mismatch, second_invoice_in_period, needs_clearance, order_match_deviation, sample_due. Treat unknown codes as a reason against.
agreementMatch.links array of object yes One entry per effective assignment (automatic, manual or confirmed).
agreementMatch.links[].confidential boolean yes true for a confidential contract. Then every field except result is null.
agreementMatch.links[].agreementId string (uuid), nullable yes Id of the contract in fineelik.
agreementMatch.links[].number string, nullable yes Number of the contract in fineelik.
agreementMatch.links[].externalNumber string, nullable yes Number of the contract at the partner or in the leading system, or null.
agreementMatch.links[].matchSource string, nullable yes auto, suggested (confirmed by a person) or manual. One of: auto, suggested, manual.
agreementMatch.links[].result string yes Result of the check: ok, deviation or unchecked. One of: ok, deviation, unchecked.
agreementMatch.links[].currency string, nullable yes Currency of the contract (ISO 4217).
agreementMatch.links[].expectedAmount string, nullable yes Expected amount for the period of the invoice (net or gross as set in the contract). Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].actualAmount string, nullable yes Actual amount of the invoice or of its assigned positions. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].deviationAmount string, nullable yes Actual minus expected amount (positive above the expected amount). Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].deviationPercent string, nullable yes Deviation in percent of the expected amount, two decimals.
agreementMatch.links[].allowedUpAmount string, nullable yes Allowed deviation upwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].allowedDownAmount string, nullable yes Allowed deviation downwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$.
agreementMatch.links[].externalGuid string, nullable yes Default: null.