Skip to main content
An Instrument is the CRM record that associates a Holder with a Ledger Account in Midaz. It stores the ledgerId and accountId for that association, together with banking details, regulatory fields, metadata, and related parties. Instruments keep CRM context separate from the transactional Ledger. The Ledger remains the balance and movement record. The Instrument holds the context associated with a Holder and its Ledger Account.

​
Create an Instrument

Create an Instrument in the scope of a Holder. The creation input requires ledgerId and accountId for the associated Ledger Account. The ledger and the account must exist in the organization. The bankingDetails object can contain branch, account, type, openingDate, closingDate, iban, countryCode, and bankId. Its individual fields are optional. Midaz rejects banking details whose bankId, branch, and account another Instrument in the organization already holds. An Instrument response includes its id, holderId, ledgerId, accountId, document, type, timestamps, and any configured banking, regulatory, metadata, or related-party data. To open the Ledger Account and its Instrument in one call, use POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{id}/accounts. The Holder in the path owns the new Account. The body takes the Account fields and, optionally, bankingDetails, regulatoryFields, and relatedParties. When the body has none of these three, Midaz creates only the Account. A 201 response carries account and instrument. When Midaz creates the Account but cannot write the Instrument, instrument is null and instrumentError carries status and reason. The Account stays, and you can create its Instrument separately. Use regulatoryFields.participantDocument to store the participant document when it applies. regulatoryFields.accountType accepts DEPOSIT, SAVINGS, INVESTMENT, OTHER_FINANCIAL_INVESTMENTS, NON_RESIDENT, or PAYMENT. An Instrument can include related parties. Each related party requires document, name, role, and startDate. The role is PRIMARY_HOLDER, LEGAL_REPRESENTATIVE, or RESPONSIBLE_PARTY. The id and endDate fields are optional, and endDate must not be before startDate.

​
Manage Instruments

The Midaz API lets you:
  • List Instruments for an organization.
  • Create an Instrument for a Holder.
  • Retrieve, update, or delete an Instrument in the scope of its Holder.
  • Delete a related party from an Instrument.
Use the Midaz API reference for the current request and response schema.

​
Next steps

Holders

Learn about the Holder associated with an Instrument.

Accounts

Learn how Midaz Ledger Accounts hold balances and movements.