Get started

    Quickstart

    Create a key, then send your first customer, invoice, and payment to HelloLedger in about ten minutes.

    Before you start

    You need a HelloLedger company and admin access to it. A company admin creates API keys; if that isn't you, ask the admin to create one and share it with you securely.

    Every request goes to https://api.helloledger.ai over HTTPS. Keep the secret on your server. Never put it in browser code, mobile apps, logs, or URLs.

    Building for many companies? Use Connect HelloLedger so each user connects their own company from your app, without copying keys.

    1. Create a key

    • In HelloLedger, open Profile → Developers and select New developer key.
    • Name the key and set Integration to your app's name (for example, acme-rent). Records are matched by integration, so a replacement key finds the same customers and invoices.
    • Pick the company, choose the Property management / receivables sync template, and create the key.
    • Copy the secret. HelloLedger stores only a hash and can't show it again.
    bash
    export HL_API_KEY=YOUR_API_SECRET

    2. Check the key

    whoami returns the companies and scopes on the key, plus your rate limits. Use the company_id it returns in every other call.

    GET
    curl "https://api.helloledger.ai/v1/whoami" \
  -H "Authorization: Bearer $HL_API_KEY"
    Response
    {
  "client_id": "hl_live_…",
  "purpose": "developer",
  "integration": "acme-rent",
  "scopes": ["coa:read", "companies:read", "customers:write", "invoices:write", "items:read", "payments:write"],
  "companies": [{ "company_id": "1234", "company_name": "YOUR BUSINESS NAME" }],
  "requests_per_minute": 120,
  "requests_per_day": 5000,
  "client_ip": "203.0.113.9",
  "allowed_ips": []
}

    3. Look up items and accounts

    Invoice lines point at a product or service (item). Payments land in a deposit account: your bank account, or a clearing account when a processor pays out in batches. Save these IDs in your app's settings.

    Products and services · GET
    curl "https://api.helloledger.ai/v1/companies/{company_id}/items" \
  -H "Authorization: Bearer $HL_API_KEY"
    Chart of accounts · GET
    curl "https://api.helloledger.ai/v1/companies/{company_id}/coa" \
  -H "Authorization: Bearer $HL_API_KEY"

    4. Send a customer

    Use your own ID in the URL. Sending the same request again is safe; it returns the existing customer.

    PUT
    curl -X PUT "https://api.helloledger.ai/v1/companies/{company_id}/customers/by-external-id/stu_1001" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jamie Rivera",
  "email": "jamie@example.com",
  "metadata": {
    "unit": "4B"
  }
}'

    5. Send an invoice

    Each charge becomes its own invoice on the customer. HelloLedger posts it to the ledger right away (A/R up, income up) and does not email anyone.

    PUT
    curl -X PUT "https://api.helloledger.ai/v1/companies/{company_id}/invoices/by-external-id/chg_2026_10_rent_1001" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_external_id": "stu_1001",
  "date": "2026-10-01",
  "due_date": "2026-10-05",
  "memo": "October rent",
  "lines": [
    {
      "item_id": "66f1a2b3c4d5e6f708091a2b",
      "description": "October rent",
      "amount": "850.00"
    }
  ]
}'

    6. Record the payment

    Each payment is recorded on its own and applied to the invoice it paid, so A/R shows exactly which charges are still open.

    PUT
    curl -X PUT "https://api.helloledger.ai/v1/companies/{company_id}/customer-payments/by-external-id/pay_pi_3Q8x" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_external_id": "stu_1001",
  "date": "2026-10-03",
  "amount": "850.00",
  "deposit_account_id": "66f1a2b3c4d5e6f708091c3d",
  "method": "ach",
  "reference": "pi_3Q8x",
  "applications": [
    {
      "invoice_external_id": "chg_2026_10_rent_1001",
      "amount": "850.00"
    }
  ]
}'

    7. See it in HelloLedger

    Open the company in HelloLedger: the customer is under Customers, the invoice shows as paid, and A/R aging no longer lists it. Profile → Developers → Activity shows every request the key made, with its result and request ID.

    Next, read Idempotency and Errors, then the property management guide for the full daily sync.