Skip to content

Table of contents

Cozy Bank doctypes

Cozy can store and manipulate bank related datas, distributed across several doctypes.

This doctype store information about Bank application settings. There is only one document, by default:

  notifications: {
    amountMax: {
      enable: false,
      value: 30

The doctype also stores the following data: - lastImportSuccess: {Object} - Information on the last successful import - savedTransactionsCount: {number} - Number of successfully imported operations - balancesNotifications: {Object} - Informations on the latest accounts balances notified - <accountId>: {string} - Last notified balance of the account

This doctype stores information about a Bank account:

  • label: {string} - The bank account label (e.g. John Doe Bank Account)
  • institutionLabel: {string} - The financial institution name the bank account belongs to
  • balance: {number} - The current account balance
  • type: {string} - The account type in the list ['none', 'bank', 'cash', 'asset', 'credit card', 'liability']
  • number: {string} - The bank account number in its institution
  • iban: {string} - The bank account international identifier
  • serviceID: {number} - In case of external service used to import transactions, this key can store the service’s account ID; can be undefined is the account isn’t managed by any external service
  • vendorId: {string} - Id of the bank account on the vendor side
  • loan: {Object} - Specific properties for loan accounts. Will be undefined for all other account types
  • contactName: {string} - The name of the contact in the credit institution
  • totalAmount: {number} - The total amount of the loan
  • availableAmount: {number} - The currently available amount
  • usedAmount: {number} - The amount already used
  • subscriptionDate: {date} - The date on which the loan has been subscribed
  • maturityDate: {date} - The end date of the loan
  • nextPaymentAmount: {number} - The amount of the next payment
  • nextPaymentDate: {date} - The date of the next payment
  • rate: {number} - The loan rate (between 0 and 100)
  • nbPaymentsLeft: {number} - The number of remaining payments
  • nbPaymentsDone: {number} - The number of payments made
  • nbPaymentsTotal: {number} - The total number of payments
  • lastPaymentAmount: {number} - The amount of the last payment
  • lastPaymentDate: {date} - The date of the last payment
  • accountLabel: {string} - The loan account label
  • insuranceLabel: {string} - The insurance label
  • duration: {number} - The loan duration in months
  • relationships: {Object} - Relationships to other documents
  • connection: {HasOne<io.cozy.accounts>} The account used to retrieve this document. This is used by Harvest to be able to edit an through the “Configuration” tab of an io.cozy.accounts.
  • checkingsAccount: {HasOne<>} - In case of a credit card account, links to the bankaccount on which all the transactions will be debited at the end of the month
  • owners: {HasMany<io.cozy.contacts>} - List of owners for this account


  "_id": "2165d9a310deadbeeffc08d54c45102",
  "balance": 1337.73,
  "institutionLabel": "Société Générale (Particuliers)",
  "label": "Livret Dévelop. Durable (x1337)",
  "linxoId": "123456",
  "metadata": {
    "version": 1
  "number": "03791 00048085818",
  "shortLabel": "Livret Dévelop. Durable",
  "type": "Savings",
  "relationships": {
    "connection": {
      "_id": "2165d9a310deadbeeffc08d54c45404",
      "_type": "io.cozy.accounts"

This doctype stores aggregated data about bank accounts:

  • periodStart: {date} - The start of the reference period
  • periodEnd: {date} - The end of the reference period
  • income: {number} - The average income on the reference period
  • additionalIncome: {number} - The average additional income on the reference period
  • mortgage: {number} - The average mortgage expense on the reference period
  • loans: {number} - The average total loans expense on the reference period
  • fixedCharges: {number} - The average fixed charges on the reference period
  • currency: {string} - A 3 uppercased chars defining the currecny used for the transaction as stated in ISO4217


  • account: {object} - The associated account


  "_id": "f1aacd3254509687c07e48279b42cd50",
  "periodStart": "2019-03-01T00:00:00",
  "periodEnd": "2019-06-30T23:59:59",
  "income": 2345.67,
  "additionalIncome": 123.45,
  "mortgage": 567.89,
  "loans": 678.9,
  "fixedCharges": 234.56,
  "currency": "EUR",
  "relationships": {
    "account": {
      "data": {
        "_id": "f1aacd3254509687c07e48279b42f3de",
        "_type": ""

This doctype stors informations about a bank transaction:

  • label: {string} - The label describing the transaction
  • type: {string} - A type in the list : ['none', 'credit card', 'cash', 'check', 'transfer', 'internal transfer', 'debit card', 'deposit', 'financial fee', 'direct debit']
  • date: {date} - The debit/credit date of the transaction on which the account is debited/credited. Is different from the realizationDate with deferred debit cards
  • realisationDate: {date} - The realization date of the transaction on which the operation really occured
  • applicationDate: {string} - The date the transaction is affected to, after a manual modification
  • dateOperation: {date} - The date the transaction is registered in the account
  • dateImport: {date} - The date the transaction is imported (can differ of the date of creation of the document as the import can be done by an external service)
  • amount: {number} - The amount of the transaction
  • currency: {string} - A 3 uppercased chars defining the currecny used for the transaction as stated in ISO4217
  • automaticCategoryId: {string} - A category that apply to the transaction and is automatically calculated. This property should be hydrated by the connector. See the « categories » section below to know more about categories
  • manualCategoryId: {string} - A category that apply to the transaction and is manually selected by the user
  • cozyCategoryId: {string} - A category found by Cozy
  • cozyCategoryProba: {number} - The probability of Cozy category
  • localCategoryId: {string} - A category found by Cozy, based on the user recategorization habits
  • localCategoryProba: {number} - The probability of local category
  • account: {identifier} - The related account id the transaction belongs to
  • bills: {array[]} - List of bills id.
  • reimbursements: {array[]} - List of bills id.
  • creditOperations: {array[]} - List of credit operations id
  • debitOperations: {array[]} - List of debit operations id
  • parent: {_id} - In case of a split transaction, the one refers the global transaction the split one belongs to
  • vendorId: {string} - Id of the transaction on the vendor side
  • vendorAccountId: {string} - Id of the transaction’s account on the vendor side

For the dates, any string or integer which can be interpreted by new Date(date) is possible but the best the result of Date.toString() -> like ‘Fri Mar 09 2018 19:04:40 GMT+0100 (CET)’ which contains the time zones.


There are up to four categories that can be assigned to a document. But there is only one that a connector has to set when retrieving the transactions from a bank: automaticCategoryId. This property has to be one of the categories ID listed here. If you want to see more human labels, you can check the translations of each label in english or french.

Other category properties are to be set by other sources: the user or Cozy Banks services.


  "_id": "f0426fdeadbeef55755ee7f4d6555",
  "account": "15fb6402426bcdeadbeeffd5f4587bb",
  "amount": 10,
  "automaticCategoryId": "400110",
  "currency": "EUR",
  "date": "2017-09-22 00:00:00+01:00",
  "dateOperation": null,
  "label": "M  PIERRE RICHARD",
  "linxoId": "845811337",
  "cozyCategoryId": "400110",
  "cozyCategoryProba": 0.9323,
  "metadata": {
    "dateImport": "2018-03-09T09:23:40.075Z",
    "version": 1
  "originalBankLabel": "VIR RECU    5383518660S DE: M  PIERRE RICHARD J MOTIF: Cascade REF: NOT PROVIDED",
  "type": "transfer"

This doctype stores a year of daily balances :

  • year: {number} - The year of the balances
  • balances: {object} - A day (YYYY-MM-DD format) / balance (number) map


  • account: {object} - The associated account


  "_id": "f1aacd3254509687c07e48279b42cd50",
  "year": 2018,
  "balances": {
    "2018-01-01": 8000,
    "2018-01-02": 8000.42,
    "2018-01-03": 1337
  "metadata": {
    "version": 1
  "relationships": {
    "account": {
      "data": {
        "_id": "f1aacd3254509687c07e48279b42f3de",
        "_type": ""

Stores a recurrence group information. Those objects are created by the recurrence service that tries to find recurring transactions. Transactions that are found as recurrent have a HasOne relationship to a object.

  • manualLabel: {string} - The year of the balances
  • automaticLabel: {string} - A day (YYYY-MM-DD format) / balance (number) map
  • amounts: {Array} - Amounts that can be matched to the recurrence (come from the transactions)
  • categoryIds: {Array} - Category ids of the transactions that have been linked
  • status: {Enum<“ongoing”,”finished”>} - A recurrence can be stated as “finished” if transactions should not longer match it. For example if a telco contract has finished.
  • stats: {Object} - Statistics used during matching
  • stats.deltas.median : Median time distance in days between operations. For example, for a monthly recurrence, this should be 30.
  • latestDate: {String} Date of the last transaction that is part of the recurrence. This is used to compute the next occurence of the recurrence
  • latestAmount: {number} Amount of the last transaction that is part of the recurrence.
  • accounts: {Array} Ids of the bank accounts that have participated to the recurrence. This is used to compute planned transactions.

Groups banks accounts together.

  • label: {string} - Name of the group
  • accounts: {Array} - Ids of


  "_id": "2a432e54822e7caeed02367a6e1f5739",
  "accounts": [
  "id": "2a432e54822e7caeed02367a6e1f5739",
  "label": "My Group"

Used to make a transfert

  • vendorAccountId :


  "_id": "recipient_internal_1",
  "category": "internal",
  "bankName": "Caisse d'Épargne",
  "bic": "CEPAFRPP627",
  "label": "Isabelle checkings",
  "currency": "EUR",
  "iban": "FR3330002005500000157841Z27",
  "vendorLastUpdate": "2020-02-12 16:12:58",
  "vendorAccountId": 1,
  "deleted": null