Classify and Connect Bank Transactions to Invoices and Receipts

curl -G 'https://api.enlivy.com/organizations/<organization_id>/bank-transaction-cost-types' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=50' \
  -H "Authorization: Bearer $ENLIVY_API_TOKEN" \
  -H 'Accept: application/json'

const baseUrl = "https://api.enlivy.com";
const token = process.env.ENLIVY_API_TOKEN;
const organizationId = "<organization_id>";

const query = new URLSearchParams({
  page: "1",
  limit: "50",
});
const result = await fetch(`${baseUrl}/organizations/${organizationId}/bank-transaction-cost-types?${query}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
  },
}).then((response) => response.json());

curl -X POST 'https://api.enlivy.com/organizations/<organization_id>/bank-transaction-cost-types' \
  -H "Authorization: Bearer $ENLIVY_API_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "title_lang_map": {
    "en": "Client Payment",
    "ro": "Încasare client"
  },
  "connection_required": true,
  "connection_types": [
    "invoice",
    "receipt"
  ],
  "organization_bank_transaction_cost_type_id": null
}'

const baseUrl = "https://api.enlivy.com";
const token = process.env.ENLIVY_API_TOKEN;
const organizationId = "<organization_id>";

const result = await fetch(`${baseUrl}/organizations/${organizationId}/bank-transaction-cost-types`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title_lang_map: {
      en: "Client Payment",
      // per-locale map
      ro: "Încasare client",
    },
    // does a transaction of this type have to be linked to a business entity?
    connection_required: true,
    // which entity types it may be connected to (required when connection_required = true)
    // options: invoice | receipt | payslip | bank_transaction | user
    connection_types: [
      "invoice",
      "receipt",
    ],
    // optional: parent cost type for a nested / hierarchical category
    organization_bank_transaction_cost_type_id: null,
  }),
}).then((response) => response.json());

# state: backlog | classified | connected | connected_partially | danger | trashed
# find transactions connected to a specific entity, send BOTH params together:
# `&connection_entity_type=invoice&connection_entity_id=invoice_id` +
# free-text search with q=... (min 3 chars) instead of ids
curl -G 'https://api.enlivy.com/organizations/<organization_id>/bank-transactions' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'state=backlog' \
  --data-urlencode 'direction=inbound' \
  --data-urlencode 'include=cost_type,connection_entities,bank_account' \
  -H "Authorization: Bearer $ENLIVY_API_TOKEN" \
  -H 'Accept: application/json'

const baseUrl = "https://api.enlivy.com";
const token = process.env.ENLIVY_API_TOKEN;
const organizationId = "<organization_id>";

// state: backlog | classified | connected | connected_partially | danger | trashed
// find transactions connected to a specific entity, send BOTH params together:
// `&connection_entity_type=invoice&connection_entity_id=invoice_id` +
// free-text search with q=... (min 3 chars) instead of ids
const query = new URLSearchParams({
  page: "1",
  limit: "20",
  state: "backlog",
  direction: "inbound",
  include: "cost_type,connection_entities,bank_account",
});
const result = await fetch(`${baseUrl}/organizations/${organizationId}/bank-transactions?${query}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
  },
}).then((response) => response.json());

# includes: organization, bank_account, cost_type, connection_entities, deleted_by_user, tag_ids
curl -G 'https://api.enlivy.com/organizations/<organization_id>/bank-transactions/<bank_transaction_id>' \
  --data-urlencode 'include=cost_type,connection_entities,bank_account' \
  -H "Authorization: Bearer $ENLIVY_API_TOKEN" \
  -H 'Accept: application/json'

const baseUrl = "https://api.enlivy.com";
const token = process.env.ENLIVY_API_TOKEN;
const organizationId = "<organization_id>";
const bankTransactionId = "<bank_transaction_id>";

// includes: organization, bank_account, cost_type, connection_entities, deleted_by_user, tag_ids
const query = new URLSearchParams({
  include: "cost_type,connection_entities,bank_account",
});
const result = await fetch(`${baseUrl}/organizations/${organizationId}/bank-transactions/${bankTransactionId}?${query}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
  },
}).then((response) => response.json());

# state is managed by classification (defaults to "backlog"), no need to set it.
# optionally classify inline with organization_bank_transaction_cost_type_id + connection_entities (see below).
curl -X POST 'https://api.enlivy.com/organizations/<organization_id>/bank-transactions' \
  -H "Authorization: Bearer $ENLIVY_API_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "hash": "unique-dedupe-key",
  "title": "Incoming transfer from Acme Studio",
  "amount": 1200,
  "currency": "EUR",
  "organization_bank_account_id": "<bank_account_id>",
  "sender_label": "ACME STUDIO SRL",
  "note": "Invoice #2026-0142 settlement"
}'

const baseUrl = "https://api.enlivy.com";
const token = process.env.ENLIVY_API_TOKEN;
const organizationId = "<organization_id>";

// state is managed by classification (defaults to "backlog"), no need to set it.
// optionally classify inline with organization_bank_transaction_cost_type_id + connection_entities (see below).
const result = await fetch(`${baseUrl}/organizations/${organizationId}/bank-transactions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    // required; unique within a bank account (import de-dup key)
    hash: "unique-dedupe-key",
    title: "Incoming transfer from Acme Studio",
    // money: signed decimal in MAJOR units (not cents)
    amount: 1200,
    // direction is DERIVED from the sign (positive = inbound, negative = outbound)
    currency: "EUR",
    organization_bank_account_id: "<bank_account_id>",
    // free-text counterpart name from the bank feed
    sender_label: "ACME STUDIO SRL",
    note: "Invoice #2026-0142 settlement",
  }),
}).then((response) => response.json());

curl -X PUT 'https://api.enlivy.com/organizations/<organization_id>/bank-transactions/<bank_transaction_id>' \
  -H "Authorization: Bearer $ENLIVY_API_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "organization_bank_transaction_cost_type_id": "<cost_type_id>",
  "connection_entities": [
    {
      "connection_entity_type": "invoice",
      "connection_entity_id": "<invoice_id>",
      "amount": 1000
    },
    {
      "connection_entity_type": "receipt",
      "connection_entity_id": "<receipt_id>",
      "amount": 200
    }
  ]
}'

const baseUrl = "https://api.enlivy.com";
const token = process.env.ENLIVY_API_TOKEN;
const organizationId = "<organization_id>";
const bankTransactionId = "<bank_transaction_id>";

const result = await fetch(`${baseUrl}/organizations/${organizationId}/bank-transactions/${bankTransactionId}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    // 1. Classify, assign a cost type. Moves state: backlog -> classified.
    organization_bank_transaction_cost_type_id: "<cost_type_id>",
    // 2. Reconcile, link the transaction to what it pays for.
    //    connection_entity_type must be one of the cost type's allowed connection_types.
    //    The array is an UPSERT:
    //        { connection_entity_type, connection_entity_id, amount }  -> create a link
    //        { id }                                                    -> keep an existing link
    //        { id, _deleted: true }                                    -> remove a link
    //    (omitting an existing link does NOT delete it)
    //    Amounts covering the full transaction -> "connected"; partial -> "connected_partially".
    connection_entities: [
      {
        connection_entity_type: "invoice",
        connection_entity_id: "<invoice_id>",
        amount: 1000,
      },
      {
        connection_entity_type: "receipt",
        connection_entity_id: "<receipt_id>",
        amount: 200,
      },
    ],
  }),
}).then((response) => response.json());

# analyticsType: summary | history_monthly
curl -G 'https://api.enlivy.com/organizations/<organization_id>/bank-transactions/analytics/summary' \
  --data-urlencode 'start_date=2026-01-01' \
  --data-urlencode 'end_date=2026-12-31' \
  --data-urlencode 'direction=outbound' \
  --data-urlencode 'convert_to_currency=EUR' \
  -H "Authorization: Bearer $ENLIVY_API_TOKEN" \
  -H 'Accept: application/json'

const baseUrl = "https://api.enlivy.com";
const token = process.env.ENLIVY_API_TOKEN;
const organizationId = "<organization_id>";
const analyticsType = "summary";

// analyticsType: summary | history_monthly
const query = new URLSearchParams({
  start_date: "2026-01-01",
  end_date: "2026-12-31",
  direction: "outbound",
  convert_to_currency: "EUR",
});
const result = await fetch(`${baseUrl}/organizations/${organizationId}/bank-transactions/analytics/${analyticsType}?${query}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
  },
}).then((response) => response.json());

# soft delete, restore via POST /bank-transactions/restore/{transactionId}
curl -X DELETE 'https://api.enlivy.com/organizations/<organization_id>/bank-transactions/<bank_transaction_id>' \
  -H "Authorization: Bearer $ENLIVY_API_TOKEN" \
  -H 'Accept: application/json'

const baseUrl = "https://api.enlivy.com";
const token = process.env.ENLIVY_API_TOKEN;
const organizationId = "<organization_id>";
const bankTransactionId = "<bank_transaction_id>";

// soft delete, restore via POST /bank-transactions/restore/{transactionId}
const result = await fetch(`${baseUrl}/organizations/${organizationId}/bank-transactions/${bankTransactionId}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
  },
}).then((response) => response.json());