Confirma Finance Integrations API
    • Introduction
    • Authentication
    • Environments
    • Data validation
    • Contact information
    • Go Live & Deployment Guide
    • Services
      • Services
      • Invoice Intermediation service
      • Invoice Lifecycle Service
      • Debt Collection Services
      • Accounting integrations
    • Core endpoints
      • Onboarding
        • Introduction to onboarding
        • Create a new client
        • Validate access token
        • Renew access token
      • Invoices
        • Introduction to Invoices
        • Create an invoice
        • Create an Invoice Action
        • Retrieve case details
        • Retrieve distribution Information
      • Payments
        • Introduction to Payments
        • Retrieve Payments
        • Retrieve settlements
      • Accounting
        • Introduction to accounting
        • Invoice
          • Invoice
        • Ledger
          • Ledger
          • Ledger
        • Payment
          • Payment
          • Payment
    Need help?

    Data validation

    This document describes data types and validation rules used in the Partner API. Request and response data is validated according to these rules.

    Type validation#

    When a request or response contains a data type, the content is validated according to the following rules.
    TypeValidation ruleDescription
    currencyCodeISO 4217Three-letter codes (e.g. EUR, SEK, NOK, DKK)
    countryCodeISO 3166-1 alpha-2Two-letter codes (e.g. FI, SE, NO, DK)
    languageCodeISO 639-1Two-letter codes (e.g. FI, SV, NO, DK, EN)
    postalCodePostal code validationValidated against the postal country
    dateISO 8601Date format (e.g. YYYY-MM-DD)
    number<double>Floating point, 2 decimalsExample: 100.25
    emailEmail validation (W3C Standard)Validates email address with RegExp format
    websiteCommon URL validation patternValidates website URL

    Invoice Type#

    Data format: String
    The invoice type determines how the invoice is handled by the service.
    ValueDescription
    INVOICEStandard sales invoice; default in the invoice cycle.
    CREDIT_NOTECredited invoice; must include a reference to the original invoice.
    REMINDERReminder invoice with the same information as the original; may be issued multiple times.
    AUTO_PAYMENT_INVOICEAuto payment (direct payment) invoice; delivered as postal letter and EDI invoice for net bank handling.
    COLLECTIONUsed to initiate a new debt collection case from the invoice data, without generating a printout.
    FACTORINGFactoring invoice - evaluated and, upon approval, acquired by financier.

    Invoice Status#

    Data format: String
    Status reflects the invoice’s state in the distribution process. Other attributes provide more detail about what happened after distribution.
    ValueDescription
    PAUSEDInvoice on hold; awaits full validation or other processing before distribution. Default for new records before validation.
    DRAFTInvoice not yet completed for distribution (“Invoice Draft”).
    ACCEPTEDInvoice accepted and validated for distribution.
    INVOICEDInvoice has been distributed.
    CREDITEDInvoice credited; payment control can update the original invoice status automatically.
    INTERMEDIATEDInvoice intermediated and distributed successfully (intermediation-only service level).
    MANUALManual approval required before distribution (service level with manual approval).
    ERRORValidation failed or mandatory information missing for distribution.
    DUPLICATEDuplicate invoice (same number); processing of invoices with the same number stopped.

    Distribution Methods#

    Data format: String
    A distribution method must be defined for each invoice; it determines how the invoice is printed and delivered.
    ValueDescription
    EMAILInvoice sent by email to a verified recipient.
    EDIElectronic delivery (Finvoice or EDI).
    POSTALInvoice sent by mail to a verified postal address.
    MULTICHANNELService chooses the best method from buyer/recipient parameters. Evaluation order: EDI → EMAIL → POSTAL.

    Entity Type#

    Data format: String
    Recipient type: consumer or legal entity (company). Mandatory; affects payment control.
    ValueDescriptionRemarks
    CONSUMERRecipient identified as a consumer.SSN recommended if available.
    BUSINESSRecipient confirmed as a company.Company business code is mandatory.

    Interest Rate Type#

    Specifies how the interest rate is determined for an invoice on submission.
    ValueDescriptionRemarks
    REFERENCE_RATERate based on late payment interest (Finnish law): reference rate + legally defined margin.Default on most invoices.
    CUSTOM_RATERate explicitly provided in the submission.Manually defined; used e.g. in business contracts.

    Financial Payment Types#

    Financial invoices (e.g. factoring) must be labeled with a financial payment type.
    ValueDescriptionRemarks
    NONENo payment type used.Default.
    FLFinancial Loan (Factoring product).Use when the invoice is a factoring invoice.

    Processing stages#

    Stages of a case in the debt collection lifecycle.
    StageDescription
    PAYMENT_CONTROLInitial monitoring; payments and due dates are controlled.
    NEWNew case entered.
    NO_LEVELPreliminary status.
    VOLUNTARY_COLLECTIONVoluntary collection status.
    TRATTATratta proceedings status.
    REMINDER_SERVICEReminders sent to the debtor for overdue amounts.
    COLLECTIONActive debt collection (contact, negotiations, payment plans, etc.).
    POST_COLLECTIONFollow-up after active collection (agreements, write-off, credit loss).
    JUDICIAL_COLLECTIONLegal proceedings to recover the debt (e.g. subpoenas).
    PAYMENT_PLANPayment plan status.
    BANKRUPTCY_PROCEDUREBankruptcy proceedings status.
    DEBT_CONSOLIDATIONDebt consolidation status.
    CASE_CLOSEDCase closed.

    Case action types#

    Types of actions that can be issued for a case.
    Action typeDescription
    INVOICE_CREATEDInvoice saved in the invoice service repository.
    INVOICE_PRINTEDTimestamp when the invoice was printed by the distribution system.
    INVOICE_DELIVEREDTimestamp when the invoice was delivered by the distribution system.
    INVOICE_TRANSFERREDTimestamp when the invoice was transferred to payment control.
    DISTRIBUTION_METHOD_UPDATEDTimestamp when distribution method was updated; includes previous and current values.
    STATUS_CHANGEDTimestamp when invoice status changed; includes previous and current values.
    FAILURETimestamp when distribution failure was detected; includes previous and current values.

    Timeline event types#

    Events that appear on the invoice timeline.
    Event typeDescription
    INVOICE_CREATEDInvoice saved in the invoice service repository.
    INVOICE_PRINTEDTimestamp when the invoice was printed by the distribution system.
    INVOICE_DELIVEREDTimestamp when the invoice was delivered by the distribution system.
    INVOICE_TRANSFERREDTimestamp when the invoice was transferred to payment control.
    DISTRIBUTION_METHOD_UPDATEDTimestamp when distribution method was updated; includes previous and current values.
    STATUS_CHANGEDTimestamp when invoice status changed; includes previous and current values.
    FAILURETimestamp when distribution failure was detected; includes previous and current values.
    Previous
    Environments
    Next
    Contact information
    Built with