API & Developers · Commingle

Commingle provides an API that lets you securely add transactions to your account from outside the app. You can use it with your own scripts and automations, connect other services or let an AI agent add transactions to Commingle on your behalf. Your financial data remains protected with end-to-end encryption – transactions are encrypted before they are sent to Commingle, so the API never needs access to their unencrypted contents. This guide explains how to obtain your API key, prepare and encrypt transaction data, and send transactions to Commingle correctly.

Coming soon

Get your API key

In Commingle, go to Main Menu → Settings → API access. From there, you can generate an API key that allows external applications and automations to add transactions to your account. This screen also contains your public key, which is required to encrypt transaction data before sending it to Commingle.

Your API key looks like this:

00000000-0000-0000-0000-000000000000_UserId

Keep your API key private. If you believe it may have been compromised, generate a new one from the same screen. Your previous key will be invalidated immediately.

Coming soon

Add transactions endpoint

POSThttps://api.commingle.app/v1/transactions

Request

# Encrypt locally on the client
envelope = encrypt(publicKey, {
  "type": "expense",
  "title": "Coffee",
  "amount": "8.99 USD",
  ...
})

# Send only encrypted data to Commingle
[
  {
    "idempotency": "txn_20260928_001",
    "encryptedData": envelope.encryptedData,
    "encryptedKey": {
      "ephemeralPublicKey": envelope.encryptedKey.ephemeralPublicKey,
      "wrappedContentKey": envelope.encryptedKey.wrappedContentKey
    },
    "nonce": envelope.nonce
  },
  ...
]

Response

[
  {
    "id": "transaction_123",
    "idempotency": "txn_20260928_001"
  }
]

Please check the Python example for a fully working implementation, including e2e encryption. You only need to provide your API key and your public key. For clarity, the request above uses full, descriptive field names. The actual API uses shorter field names and acronyms – refer to the Python example for the exact format. The idempotency value is optional, but recommended to prevent the same transaction from being uploaded more than once by mistake.

API pricing

Using the API consumes your Commingle credits. Each request costs 1 credit + 1 credit for each transaction successfully added. For example, a request that adds only 1 transaction costs 2 credits, but a request that adds 10 transactions costs 11 credits.

Tips

Test safely. Since the actual transaction structure is end-to-end encrypted, Commingle cannot perform deep validation of its contents. Consider creating a temporary Commingle account while testing your integration. Verify that your transactions appear correctly in the app, then replace the credentials with those from your main account.
Avoid duplicates. Provide a stable idempotency value for each transaction. Commingle uses it to prevent the same transaction from being added more than once.
Find IDs. You can find and copy IDs for categories, wallets, events and other resources directly from their edit forms in Commingle.
Personal transactions only. Shared transactions with friends cannot currently be added through the API.
One endpoint. Only the endpoint for adding transactions is currently exposed by the Commingle API.

Open source

Open-source parts of Commingle and how we share them.

Friends

How balances work between you and your friends.