Getting started 👋

Cardda is a corporate spend management platform: cards, bank transfers, and accounting in one API. This guide takes you from zero to your first authenticated request in under 10 minutes.

💬

Need help? Email [email protected] or join our Discord community — the engineering team hangs out there.

What you'll do in this quickstart

1. Create an API key in the Cardda dashboard.
2. Discover the company you want to operate on (GET /v1/companies).
3. Make your first authenticated request with the company-id header.
4. Filter the response.
5. Subscribe to a webhook.

After this you'll be ready to follow any of the Tutorials for end-to-end integration flows.

1. Create an API key

API keys belong to a Cardda user and can act on every company that user is a member of.

1. Sign in to app.cardda.com.
2. Open Settings → Developers → API Keys.
3. Click Create key, give it a descriptive name (e.g. accounting-prod), and copy the secret. You will not see it again.

🔐

Treat the API key like a password. Store it in your secret manager, never in the repo.

Full details: Authentication & API keys.

2. List the companies you have access to

Cardda is multi-tenant. The first call you make tells you which company UUIDs your key can operate on.

curl https://api.cardda.com/v1/companies \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Holdings",
      "country": "CL",
      "tax_id": "76123456-7"
    }
  ],
  "total": 1
}

Pick the id of the company you want to operate on. We'll call it COMPANY_ID from now on.

📘

The full conventions for company-id (when it's required, error cases, caching strategies) live on The company-id header.

3. Your first authenticated request

Let's list bank transactions for the company you picked. Notice the two headers — Authorization and company-id:

curl https://api.cardda.com/v1/banking/bank_transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "company-id: COMPANY_ID"

[
  {
    "id": "1d8a4b6c-...",
    "amount": 1250000,
    "currency": "CLP",
    "status": "authorized",
    "recipient": { "name": "Acme Vendor", "rut": "76543210-K" },
    "created_at": "2026-04-28T14:30:00Z"
  }
]

If you see an empty array, that's expected — there are simply no bank transactions on that company yet. Keep going.

4. Filter the response

The Cardda API supports MongoDB-style query operators on every index endpoint:

# Only authorized transactions over CLP 1M created since April 1st, sorted newest first.
# Let curl encode the operator brackets and quotes for you with --data-urlencode:
curl -G 'https://api.cardda.com/v1/banking/bank_transactions' \
  --data-urlencode 'status[$in]=["authorized"]' \
  --data-urlencode 'amount[$gte]=1000000' \
  --data-urlencode 'created_at[$gte]=2026-04-01T00:00:00Z' \
  --data-urlencode '_order=desc' \
  --data-urlencode '_field=created_at' \
  --data-urlencode '_start=0' \
  --data-urlencode '_end=100' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "company-id: COMPANY_ID"

⚠️

URL-encode operator parameters. Filter keys like status[$in], amount[$gte], and created_at[$gte] contain [, ], $, and (for $in) " — characters most shells and HTTP clients require to be percent-encoded. The curl -G --data-urlencode form above handles it automatically. If you assemble the query string yourself, the equivalent encoded URL is …/bank_transactions?status%5B%24in%5D=%5B%22authorized%22%5D&amount%5B%24gte%5D=1000000&….

Operators supported: $gt, $gte, $lt, $lte, $in, $nin, $ne, $regex, $or, plus nested-resource queries. See Filters for the complete reference and Pagination for the page-size and ordering rules.

5. Subscribe to a webhook

When something happens you'd otherwise have to poll for, register a webhook so Cardda pushes the event to you.

Today the only available webhook is the PLH SMS verification code (used for card transaction step-up auth). The mechanics — signature verification, retries, idempotency — apply to every Cardda webhook today and to the upcoming general-purpose webhooks.

Implementation guide: Verification Codes via Webhook. General mechanics: Webhooks.

Next steps

SDK

The community-maintained Python client at github.com/cardda/cardda_python wraps most public endpoints:

from cardda_python import CarddaClient

client = CarddaClient(api_key="YOUR_API_KEY", company_id="COMPANY_ID")

# Find a specific bank transaction by ID
tx = client.banking.transactions.find("1d8a4b6c-...")
if tx.amount < 1_000_000:
    client.banking.transactions.enqueue(tx, source_account_id="...")

🧪

Sandbox. A dedicated sandbox environment is on the roadmap. Until then, contact us before pointing automated tests at production — we can provision a test company isolated from real money flows.