{ "openapi": "3.1.0", "info": { "title": "Savings Principal Equity Reserve Mutual API", "version": "1.0.0", "description": "A mock bank for the insurance hackathon. Accounts, transfers with one free-text `reference`, statements. It knows nothing about insurance: no policies, premiums, commissions or bordereaux. Money is **integer cents**; v1 is USD only.\n\n## Open your company\n\nNo paperwork. One call, no auth, returns your api key **once**:\n\n curl -s -X POST https://sbank.cork.tech/api/v1/signup -H 'content-type: application/json' \\\n -d '{\"name\":\"Acme Underwriting\",\"team\":\"1\",\"accounts\":[{\"name\":\"Operating\",\"type\":\"operating\",\"opening_balance_cents\":50000000},{\"name\":\"Premium Trust\",\"type\":\"trust\"}]}'\n\nOpen more accounts later with `POST /api/v1/accounts`. How you segregate your money (operating, premium trust, loss fund) is your decision, not the bank's.\n\n## Authenticate\n\nEvery other `/api/v1/*` call except the directory needs that api key:\n\n Authorization: Bearer rm_live_…\n\nClick **Authorize** above and paste it. CORS is open, so you can call the API straight from your own dashboard.\n\n## Send a payment\n\n curl -s -X POST https://sbank.cork.tech/api/v1/payments \\\n -H \"Authorization: Bearer $KEY\" \\\n -H 'content-type: application/json' \\\n -H 'Idempotency-Key: premium-POL-0001-2026-09' \\\n -d '{\"from_account_id\":\"acc_...\",\"to_account_number\":\"RM-0001-0003\",\"amount_cents\":125000,\"currency\":\"USD\",\"reference\":\"PREMIUM POL-0001 SEP26\",\"end_to_end_id\":\"POL-0001-SEP26\"}'\n\nSame `Idempotency-Key` and same body replays the original response; same key with a different body is a `409`. An unknown `to_account_number` is a `422`. Not enough money is a `422` with the payment recorded as `rejected`: the bank does not do overdrafts. Find other companies' account numbers in `GET /api/v1/directory`.\n\n## Payment statuses\n\n- `settled`: money moved, two postings written\n- `pending`: the bank is in manual settlement mode; it will settle or return it\n- `returned`: the bank reversed it; look for the matching `RETURN ` credit\n- `rejected`: never happened; `return_reason` says why\n\n## Reconcile\n\n curl -s \"https://sbank.cork.tech/api/v1/accounts/acc_.../statement?from=2026-09-01&to=2026-09-30&format=csv\" \\\n -H \"Authorization: Bearer $KEY\" -o statement.csv\n\nCSV columns: date, value_date, account_number, counterparty_account_number, direction (CR/DR), amount, currency, reference, transfer_id, end_to_end_id, running_balance. The reference field is free text and at most 140 characters, like a real bank's. Matching it to your invoices is your problem, on purpose.\n\n## Errors\n\n { \"error\": { \"code\": \"unprocessable_entity\", \"message\": \"No account with number `RM-0001-0099`\" } }\n\n## Admin\n\n`/admin/*` routes need the bank's own key (`ADMIN_KEY`), not a company key. Ask the bank." }, "servers": [ { "url": "https://sbank.cork.tech" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "The api key the bank issued once: rm_live_…" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Account": { "type": "object", "properties": { "id": { "type": "string" }, "account_number": { "type": "string", "examples": [ "RM-0001-0007" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "operating", "trust", "loss_fund", "other" ] }, "currency": { "type": "string", "examples": [ "USD" ] }, "status": { "type": "string", "enum": [ "active", "frozen" ] }, "balance_cents": { "type": "integer" }, "available_cents": { "type": "integer" } } }, "Payment": { "type": "object", "properties": { "id": { "type": "string" }, "from_account_id": { "type": [ "string", "null" ] }, "to_account_id": { "type": [ "string", "null" ] }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "reference": { "type": "string", "maxLength": 140 }, "status": { "type": "string", "enum": [ "pending", "settled", "returned", "rejected" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "return_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "returned_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StatementLine": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "value_date": { "type": [ "string", "null" ], "format": "date-time" }, "account_number": { "type": "string" }, "counterparty_account_number": { "type": "string" }, "direction": { "type": "string", "enum": [ "CR", "DR" ] }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "reference": { "type": "string" }, "transfer_id": { "type": "string" }, "end_to_end_id": { "type": [ "string", "null" ] }, "running_balance_cents": { "type": "integer" } } } } }, "security": [ { "apiKey": [] } ], "paths": { "/health": { "get": { "summary": "Liveness", "security": [], "responses": { "200": { "description": "The bank is open", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/signup": { "post": { "summary": "Open a company (no auth, key shown once)", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120, "examples": [ "Acme Underwriting LLC" ] }, "slug": { "type": "string", "description": "Lowercase, digits and dashes. Derived from the name if absent." }, "team": { "type": "string", "examples": [ "1", "2" ] }, "accounts": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "operating", "trust", "loss_fund", "other" ], "default": "operating" }, "opening_balance_cents": { "type": "integer", "minimum": 0, "description": "Booked as an OPENING BALANCE deposit" } } } } } } } } }, "responses": { "201": { "description": "Your company, its api key (once) and its accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "organisation": { "type": "object" }, "api_key": { "type": "string" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } } } }, "409": { "description": "Slug already taken", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/me": { "get": { "summary": "Your organisation and accounts", "responses": { "200": { "description": "Organisation and accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "organisation": { "type": "object" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/me/rotate-key": { "post": { "summary": "Rotate your api key (old one dies now, new one shown once)", "responses": { "200": { "description": "New key", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/accounts": { "get": { "summary": "List your accounts", "responses": { "200": { "description": "Accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "post": { "summary": "Open an account", "description": "Your company decides how it segregates its money. Open as many accounts as you need: an operating account, a premium trust account, a loss fund. The bank gives each one a number.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120, "examples": [ "Premium Trust" ] }, "type": { "type": "string", "enum": [ "operating", "trust", "loss_fund", "other" ], "default": "operating" }, "currency": { "type": "string", "enum": [ "USD" ], "default": "USD" }, "opening_balance_cents": { "type": "integer", "minimum": 0, "description": "Optional. Booked as an OPENING BALANCE deposit." } } } } } }, "responses": { "201": { "description": "Opened", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/accounts/{id}": { "get": { "summary": "One account", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/accounts/{id}/transactions": { "get": { "summary": "Postings on an account, newest first", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "ISO date or datetime, inclusive" }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "ISO date or datetime, inclusive" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 500 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "next_cursor from the previous page" } ], "responses": { "200": { "description": "A page of transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/StatementLine" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/accounts/{id}/statement": { "get": { "summary": "Statement for a date range", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "ISO date or datetime, inclusive" }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "ISO date or datetime, inclusive" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv", "html" ], "default": "json" } } ], "responses": { "200": { "description": "Statement", "content": { "application/json": { "schema": { "type": "object", "properties": { "opening_balance_cents": { "type": "integer" }, "closing_balance_cents": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/StatementLine" } } } } }, "text/csv": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/payments": { "get": { "summary": "Payments touching your accounts", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "settled", "returned", "rejected" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 500 } } ], "responses": { "200": { "description": "Payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "post": { "summary": "Send a payment", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Same key and body replays the original response; same key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_account_id", "to_account_number", "amount_cents" ], "properties": { "from_account_id": { "type": "string" }, "to_account_number": { "type": "string", "examples": [ "RM-0001-0003" ] }, "amount_cents": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "enum": [ "USD" ], "default": "USD" }, "reference": { "type": "string", "maxLength": 140 }, "end_to_end_id": { "type": "string", "maxLength": 64 } } } } } }, "responses": { "201": { "description": "Created; settled or pending depending on the bank settlement mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/Payment" } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Idempotency-Key reused with a different body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Unknown account, frozen account or insufficient funds (payment recorded as rejected)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/payments/{id}": { "get": { "summary": "One payment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/Payment" } } } } } }, "401": { "description": "Missing or invalid api key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Not your resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/directory": { "get": { "summary": "Every company at the bank and its account numbers", "security": [], "responses": { "200": { "description": "Directory, never balances", "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }