Developer Docs

MapleSchema normalizes upstream banking transaction payloads into a single deterministic transaction contract. This page covers authentication (Project ID + API key), the /v1/transactions/transform endpoint, and optional Insights.

This is infrastructure-style documentation: stable contract, predictable failure modes, and minimal surprises.

Quickstart

Send an upstream payload to /v1/transactions/transform. Authenticate using Project ID + API key.

Request Enterprise Access

Example: Transform a payload

The command below posts a payload and returns a deterministic batch response.

Request (curl)

curl -X POST https://api.mapleschema.com/v1/transactions/transform \
  -H "X-Project-Id: YOUR_PROJECT_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @transactions.json

Save the JSON below as transactions.json, then run the command. Replace YOUR_PROJECT_ID and YOUR_API_KEY with values issued to your org.

Sample Input (transactions.json)

{
  "aggregator_code": "flinks",
  "institution_code": "rbc_ca",
  "payload": {
    "Data": {
      "Transaction": [
        {
          "AccountId": "chq_001",
          "TransactionId": "stmt_line_1842",
          "TransactionReference": "stmt_line_1842",
          "Amount": { "Amount": "7.24", "Currency": "CAD" },
          "CreditDebitIndicator": "Debit",
          "Status": "Booked",
          "BookingDateTime": "2026-01-14T19:22:11Z",
          "ValueDateTime": "2026-01-14T19:22:11Z",
          "TransactionInformation": "TIM HORTONS #0059 / LONDON ON",
          "ProprietaryBankTransactionCode": { "Code": "POS", "Issuer": "rbc_ca" }
        }
      ]
    },
    "Links": { "Self": "https://api.flinks.com/transactions" },
    "Meta": {
      "TotalPages": 1,
      "FirstAvailableDateTime": "2026-01-01T00:00:00Z",
      "LastAvailableDateTime": "2026-01-31T23:59:59Z"
    }
  }
}

🔑 Authentication

Enterprise calls use a Project model. Every request must include:

  • X-Project-Id — identifies which project/environment is calling (e.g. prod-ledger, analytics)
  • X-Api-Key — authorizes that project’s usage
X-Project-Id: YOUR_PROJECT_ID
X-Api-Key: YOUR_API_KEY

Missing or invalid credentials return a deterministic auth error.

🔁 Transform Endpoint

  • Method: POST
  • Path: /v1/transactions/transform
  • Content-Type: application/json
  • Auth: X-Project-Id + X-Api-Key

The API accepts either: (A) raw transactions array, or (B) a full upstream payload object plus extraction context.

📥 Request Body

A) Provide transactions directly

{
  "aggregator_code": "flinks",
  "institution_code": "rbc_ca",
  "transactions": [
    {
      "AccountId": "chq_001",
      "TransactionId": "stmt_line_1842",
      "TransactionReference": "stmt_line_1842",
      "Amount": { "Amount": "7.24", "Currency": "CAD" },
      "CreditDebitIndicator": "Debit",
      "Status": "Booked",
      "BookingDateTime": "2026-01-14T19:22:11Z",
      "ValueDateTime": "2026-01-14T19:22:11Z",
      "TransactionInformation": "TIM HORTONS #0059 / LONDON ON"
    }
  ]
}

B) Provide a full upstream payload

Useful when you want MapleSchema to extract Data.Transaction (or another path) for you.

Field
Meaning
aggregator_code
Upstream provider identifier (e.g. flinks)
institution_code
Institution mapping to apply (e.g. rbc_ca)
payload
Full upstream object containing a transactions array somewhere inside
transactions_path
optional Dot-path to the transactions array (defaults to provider strategy)
include_insights
optional If true, request Insights annotations (paid/enterprise only)

If you omit both transactions and payload, the API returns a client error.

📤 Response Body

The API returns a batch response:

  • metadata — request diagnostics and counts
  • transactions — deterministic canonical transactions (sorted stably)

Sample Output (trimmed)

{
  "metadata": {
    "request_id": "req_123",
    "institution_code": "rbc_ca",
    "received_at": "2026-01-14T19:22:12Z",
    "processed_at": "2026-01-14T19:22:12Z",
    "input_count": 1,
    "output_count": 1,
    "failed_count": 0
  },
  "transactions": [
    {
      "schema_version": "transactions-v1.0",
      "transaction_fingerprint": "ms_fp_9f1c2c7b0d2a",
      "transaction_ref": "stmt_line_1842",
      "account_ref": "chq_001",
      "institution_code": "rbc_ca",
      "aggregator_code": "flinks",
      "effective_at": "2026-01-14T19:22:11Z",
      "posted_at": "2026-01-14T19:22:11Z",
      "amount": { "amount_minor": 724, "amount_raw": -7.24, "currency": "CAD" },
      "direction": "debit",
      "original_description": "TIM HORTONS #0059 / LONDON ON",
      "status": "posted",
      "mutability": "unknown",
      "normalization": { "mapping_method": "direct", "warnings": [], "input_timezone": "Z" },
      "insights": null,
      "extras": {}
    }
  ]
}

Notes: amount.amount_minor is an unsigned magnitude; sign is conveyed by direction and amount.amount_raw. Timestamps are normalized to UTC.

🧾 Canonical Transaction Fields (dot notation)

These are the fields most downstream systems depend on.

Field path
Meaning
schema_version
Contract version (currently transactions-v1.0)
transaction_fingerprint
Stable fingerprint used for collision detection
transaction_ref
Optional caller-owned transaction reference (echoed if provided)
account_ref
Optional caller-owned account reference (echoed if provided)
institution_code
Institution adapter used for normalization
aggregator_code
Upstream provider identifier
effective_at
Required canonical timestamp in UTC
posted_at
Posted time in UTC (nullable if not provided upstream)
amount.amount_minor
Unsigned magnitude in minor units (e.g. cents)
amount.amount_raw
Signed decimal helper value
amount.currency
ISO currency code (e.g. CAD)
direction
debit or credit
original_description
Raw upstream description line
status
Normalized ledger inclusion status (e.g. posted/pending)
mutability
Mutability indicator (currently unknown)
normalization.mapping_method
Mapping method used to produce the normalized object
normalization.warnings
Best-effort warnings for diagnostics (array)
normalization.input_timezone
Timezone derived from upstream timestamp offset
extras
Passthrough metadata (may include internal _ms diagnostics)

✨ Insights (optional)

Insights are optional annotations on top of the canonical transaction. They never change core fields. They are best-effort and degrade safely on provider failure.

Field path
Meaning
include_insights
Request flag (true/false). When true, Insights may be populated.
insights.category.value
Category enum value (e.g. coffee_fast_food)
insights.category.confidence
0..1 confidence score
insights.category.version
Insights version identifier
insights.category.signals
Short explanations (array of strings)
insights.category.model.provider
Provider name (e.g. gemini)
insights.category.model.model
Provider model identifier
insights.category.model.latency_ms
Best-effort latency annotation
insights.description
Best-effort cleaned description (short, non-speculative)

To request Insights, add "include_insights": true to your request body.

⚠️ Errors & limits

The API returns typed errors with a stable code, a human-safe message, and a request_id. When failures occur during extraction or mapping, responses include diagnostics (e.g. candidate paths, failed indexes).

All inquiries

Questions, access, enterprise usage, or integration help: email mapleschema@gmail.com.