# banta API - full documentation > Official documentation for the banta API - the mortgage advisory and mortgage-file management platform. API-key auth, leads, customers, mortgage files, tasks, documents, billing and milestones. Source: https://docs.banta.co.il · Index: https://docs.banta.co.il/llms.txt · OpenAPI: https://docs.banta.co.il/openapi.json API version: 1.0.0 · Generated: 2026-10-14 # Introduction The banta API connects the mortgage management platform to your other systems: marketing sites and landing pages, CRMs, automation tools (Make, Zapier, n8n), BI and internal tools. Every call operates on the data of the organization that owns the API key - and only on it. ## What you can do - **Leads** - capture leads from forms and campaigns, update their status, list and search them. - **Customers and contacts** - manage customer records and professional contacts (bankers, appraisers, lawyers). - **Mortgage files** - create and update files, including borrowers, incomes, obligations and purposes. - **File management** - tasks, notes, reminders, watchers, file contacts and milestones. - **Documents** - document statuses, signatures and generated documents (read). - **Billing** - charges, payments, calculator mixes and file analyses. - **System lists** - fixed values (employment types, mortgage types, statuses) for building forms. ## Base URL All endpoints live under: ``` https://app.banta.co.il/api-service ``` For example, listing leads: `GET https://app.banta.co.il/api-service/leads`. ## Data format - **JSON only** - requests with a body are sent with `Content-Type: application/json`, and responses are always UTF-8 JSON. - **IDs** - every identifier is a UUID. - **Dates** - ISO 8601. Date-time fields (`created_at`, `updated_at`) include a time zone; date-only fields are `YYYY-MM-DD`. - **Amounts** - numbers (not strings), in Israeli shekels (ILS) unless a field says otherwise. - **Text** - much of the data your organization stores (names, notes, statuses) is in Hebrew. Make sure your client handles UTF-8 end to end. - **Errors** - one consistent shape, see [Errors](https://docs.banta.co.il/guides/errors.md). ## Versioning and compatibility The current API version is 1.0.0. API URLs do not include a version number. Additive changes - new fields or new endpoints - can ship at any time, so write clients that ignore fields they don't recognize. Breaking changes are announced in advance on the [Changelog](https://docs.banta.co.il/guides/changelog.md). ## Docs for AI agents All of this documentation is also published as clean text for AI agents and LLMs: [`llms.txt`](https://docs.banta.co.il/llms.txt), [`llms-full.txt`](https://docs.banta.co.il/llms-full.txt) and a Markdown file per endpoint. You can also connect banta directly to Claude or ChatGPT over MCP. See [AI agents & MCP](https://docs.banta.co.il/guides/ai-agents.md). ## Support API questions: [support@banta.co.il](mailto:support@banta.co.il). Product guides (in Hebrew) are in the [Help Center](https://help.banta.co.il). This documentation is also available [in Hebrew](https://docs.banta.co.il/he/). --- # Quickstart ## 1. Create an API key 1. Sign in to banta as a user who is allowed to manage the organization's integrations. 2. Go to [Organization settings → Integrations → API](https://app.banta.co.il/organization/settings?group=integrations&tab=api). 3. Create a new key, give it a name that describes its use (for example "Website lead form") and choose its permissions. Grant the minimum you need - see [Authentication & permissions](https://docs.banta.co.il/guides/authentication.md). 4. **Copy the key right away.** It is shown only once and cannot be retrieved later. > Keep the key on the server side only (environment variables or a secrets vault). Never embed it in code that runs in a browser or a mobile app. ## 2. Your first call Fetch the five most recent leads: ```bash curl "https://app.banta.co.il/api-service/leads?limit=5" \ -H "x-api-key: $BANTA_API_KEY" ``` List responses carry a total count: ```json { "data": [ { "id": "6f1c2a4e-0b7d-4b8e-9a51-2f6c3d8e9a10", "first_name": "Israel", "last_name": "Israeli", "phone": "050-0000000", "status": "new", "created_at": "2026-10-01T09:30:00+00:00" } ], "count": 128 } ``` `count` is the number of records that match the query - not just the ones on the current page. See [Pagination & search](https://docs.banta.co.il/guides/conventions.md). ## 3. Create a lead ```bash curl -X POST "https://app.banta.co.il/api-service/leads" \ -H "x-api-key: $BANTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Israel", "last_name": "Israeli", "phone": "050-0000000", "email": "israel@example.com", "source": "website" }' ``` A successful call returns `201 Created` with the full lead, including its new `id`. ## The same call in popular languages **JavaScript (Node.js 18+):** ```js const res = await fetch('https://app.banta.co.il/api-service/leads', { method: 'POST', headers: { 'x-api-key': process.env.BANTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ first_name: 'Israel', last_name: 'Israeli', phone: '050-0000000', source: 'website', }), }) if (!res.ok) { const err = await res.json() throw new Error(`banta API ${res.status}: ${err.error} ${err.details ?? ''}`) } const lead = await res.json() ``` **Python:** ```python import os import requests res = requests.post( "https://app.banta.co.il/api-service/leads", headers={"x-api-key": os.environ["BANTA_API_KEY"]}, json={ "first_name": "Israel", "last_name": "Israeli", "phone": "050-0000000", "source": "website", }, timeout=30, ) res.raise_for_status() lead = res.json() ``` ## Next steps - Every endpoint in this reference has a **Test Request** button. Requests go straight from your browser to banta, with no intermediary server. The key you enter is kept only in the open tab and is cleared when you close it. Note that these are real requests against your organization's data. - [Authentication & permissions](https://docs.banta.co.il/guides/authentication.md) - how to scope a key down. - [Errors](https://docs.banta.co.il/guides/errors.md) and [Rate limits](https://docs.banta.co.il/guides/rate-limits.md) - how to handle failures. --- # Authentication & permissions ## API keys Every request must carry an API key in the `x-api-key` header: ```http GET /api-service/leads HTTP/1.1 Host: app.banta.co.il x-api-key: YOUR_API_KEY ``` - Keys are created in [Organization settings → Integrations → API](https://app.banta.co.il/organization/settings?group=integrations&tab=api) and shown only once. banta stores only a hash of the key. - Each key belongs to exactly one organization. Every call sees and changes only that organization's data; there is no way to reach another organization's data. - You can revoke a key at any time from the same screen, effective immediately. Keys can also have an expiry date, after which they are rejected. - Every successful write (create, update, delete) is recorded in the organization's API audit log: the key, the endpoint, the affected record, the status and the duration. Request and response bodies are not stored. > A key is equivalent to a password with access to customers' personal data. Use it server-side only, never commit it to code or git, and rotate it immediately if you suspect it leaked. ## Permissions Each key has a list of permissions. Every request is checked by **resource** and **action**: | HTTP method | Action | |---|---| | `GET` | `read` | | `POST`, `PUT`, `PATCH` | `write` | | `DELETE` | `delete` | The resources are `leads`, `customers`, `contacts`, `mortgage-files`, `tasks` and `lists`. Every route nested under a mortgage file (`/mortgage-files/{id}/...` - borrowers, notes, charges, milestones and so on) is checked against the `mortgage-files` resource. Permission values: | Value | Meaning | |---|---| | `admin` or `*` | Full access to every resource and action | | `leads:*` | Every action on one resource | | `leads:read`, `leads:write`, `leads:delete` | One action on one resource | | `read` | Read every resource | | `write` | Create and update on every resource (**not** delete) | The key creation screen offers four presets: **Read only** (`read`), **Read & write** (`read` + `write`, without deleting), **Full access** (`admin`) and **Custom**, where you pick resource/action pairs from a table. Deleting always requires an explicit permission: `admin`/`*`, `resource:*` or `resource:delete`. Example: a website lead form needs only `leads:write`. A BI dashboard needs only `read`. ## Authentication responses | Status | When | What to do | |---|---|---| | `401 Unauthorized` | The key is missing, invalid or revoked | Check the header and the key. The `reason` field says why. | | `403 Forbidden` | The key is valid but lacks permission for this action on this resource | Add the permission or create a dedicated key | `reason` values on a 401: | `reason` | Meaning | |---|---| | `missing_api_key` | The `x-api-key` header was not sent or is empty | | `malformed_api_key` | The key contains whitespace or invalid characters (usually a copy-paste error) | | `invalid_api_key` | The key does not exist, was revoked or has expired | | `auth_service_error` | A temporary failure in the authentication service. Retry in a few seconds | ```json { "reason": "invalid_api_key", "error": "Unauthorized", "status": 401 } ``` ## CORS The API returns permissive CORS headers so that the **Test Request** button in these docs works from the browser. That does **not** make it OK to call the API from client-side code in production: anyone opening the developer tools would see the key. Put a server layer (a backend, a serverless function or an automation tool) in front of the API to hold the key. --- # Pagination, search & responses ## Response shape | Call | Status | Body | |---|---|---| | List (`GET /leads`) | `200` | An object `{ "data": [...], "count": N }` | | Single record (`GET /leads/{id}`) | `200` | The record itself | | Create (`POST`) | `201` | The created record, including its `id` | | Update (`PUT` / `PATCH`) | `200` | The updated record | | Delete (`DELETE`) | `200` | A confirmation, e.g. `{ "success": true, "message": "..." }` | On paginated lists, `count` is the total number of records that match the query, not just the ones on the current page. On short, unpaginated lists (for example borrowers in a file), `count` equals the array length. ## Pagination Large lists are paginated with two parameters: | Parameter | Default | Maximum | Description | |---|---|---|---| | `limit` | `50` | `500` | Records per page | | `offset` | `0` | `1000000` | Records to skip | An invalid value (negative or non-numeric) does not return an error - it falls back to the default. A value above the maximum is capped. Results are sorted newest first (`created_at` descending) unless an endpoint says otherwise. Walking through every record: ```js async function fetchAll(path) { const limit = 500 const all = [] for (let offset = 0; ; offset += limit) { const res = await fetch(`https://app.banta.co.il/api-service${path}?limit=${limit}&offset=${offset}`, { headers: { 'x-api-key': process.env.BANTA_API_KEY }, }) if (!res.ok) throw new Error(`HTTP ${res.status}`) const { data, count } = await res.json() all.push(...data) if (data.length < limit || all.length >= count) return all } } ``` > When paging through a lot of data, mind the [rate limit](https://docs.banta.co.il/guides/rate-limits.md) of 60 requests per minute. Pages of 500 are the most efficient way through. ## Search Endpoints that support search accept a `search` parameter. Search is case-insensitive and matches the term inside several fields at once (for example name, phone and email). The exact fields are listed on each endpoint. ```bash curl "https://app.banta.co.il/api-service/customers?search=Israeli" -H "x-api-key: $BANTA_API_KEY" ``` The characters `, ( ) % _ \ " '` are stripped from the term before searching. Search for phone numbers the way they are stored, with or without dashes. ## Filtering Some lists accept extra filter parameters, for example `status` on the leads list. Available parameters are listed on each endpoint. ## PUT vs PATCH On resources that support both, `PUT` and `PATCH` behave the same: a **partial update**. Send only the fields you want to change; fields you don't send are left as they are. Fields that cannot be updated (such as `id`, `organization_id` and `created_at`) are silently ignored. If no updatable field is sent, the API returns `400 No updatable fields provided`. ## Fixed values Enum values (employment types, mortgage types, statuses and so on) are available from the endpoints under [System lists](https://docs.banta.co.il/#tag/lists). Use them to build forms instead of hard-coding values. Lead and file statuses can be customized per organization, so read them from `/leads/statuses` and `/mortgage-files/statuses`. --- # Errors ## Error response shape Every error is returned as JSON in the same shape: ```json { "error": "Lead not found or access denied", "details": "...", "status": 404 } ``` | Field | Always? | Description | |---|---|---| | `error` | Yes | A short, stable description of the error. Safe to rely on in logs and alerts. | | `status` | Yes | The HTTP status code, identical to the response status. | | `details` | No | Extra explanation, when available. | | `reason` | On 401 | Why authentication failed. See [Authentication & permissions](https://docs.banta.co.il/guides/authentication.md). | | `retry_after` | On 429 | When the next request window opens (ISO 8601). | | `code` | Sometimes | A database error code, when it is safe to expose: on 400 (e.g. `23514` for a status the organization does not define), on 409 (`23505`, a duplicate value) and on 500. | Some errors add context fields, for example `existing_link_id` when you try to link a contact that is already linked to the file. ## Status codes | Status | Meaning | What to do | |---|---|---| | `400 Bad Request` | Invalid body (malformed JSON or not an object), a missing required field, an invalid value (for example an unknown status, a malformed ID, or an ID that belongs to another organization), or an update with no updatable field | Fix the request. Don't retry it as is. | | `401 Unauthorized` | API key missing, invalid, expired or revoked | Check `reason` | | `403 Forbidden` | The key lacks permission for this action on this resource | Add the permission to the key | | `404 Not Found` | The record doesn't exist, was deleted or belongs to another organization - or the route isn't supported | Check the ID and the path | | `405 Method Not Allowed` | The HTTP method isn't supported on this route | Check which methods the endpoint supports | | `409 Conflict` | The action conflicts with the current state: an existing link, a locked note, a cancelled payment, or a duplicate unique value (such as an ID number) | Read the current record and decide how to proceed | | `429 Too Many Requests` | Rate limit exceeded | Wait until `retry_after`. See [Rate limits](https://docs.banta.co.il/guides/rate-limits.md). | | `500 Internal Server Error` | A failure on banta's side | Retry with exponential backoff; contact support if it persists. | > The API also returns `404` for a record that exists in another organization, so an ID can't be probed for existence. ## Retries - **Retry:** `429`, `500`, and network errors or timeouts. Use exponential backoff (e.g. 1, 2, 4, 8 seconds) with some jitter. - **Don't retry without changing something:** `400`, `401`, `403`, `404`, `405`, `409`. - **Careful with `POST` after a timeout:** the first request may have succeeded. The API doesn't support idempotency keys yet, so before re-sending a create, check with `search` whether the record already exists. --- # Rate limits ## The limit Each API key is limited to **60 requests per 60-second window**. The window opens with the first request and resets 60 seconds later. The limit applies per key, not per organization. A request over the limit receives `429 Too Many Requests` and is not executed: ```json { "retry_after": "2026-10-14T09:31:00.000Z", "error": "Too Many Requests", "details": "Rate limit exceeded (61 requests in window)", "status": 429 } ``` `retry_after` is when the next window opens. The API does not send a `Retry-After` header, so read the field from the body. ## Staying within the limit - **Large pages** - when listing, use `limit=500`. One page of 500 costs the same as one page of 50. - **Incremental sync** - for periodic syncs, remember when the last run happened and process only what changed instead of re-fetching everything. - **A queue on your side** - if you create many records at once (an import, say), send them from a queue at up to one request per second. - **One key per integration** - so load from one system can't block another, and revoking a single integration is easy. - **Handle 429** - wait until `retry_after`, then retry. ```js async function bantaFetch(url, init, attempt = 0) { const res = await fetch(url, init) if (res.status !== 429 || attempt >= 3) return res const body = await res.json().catch(() => ({})) const waitMs = body.retry_after ? Math.max(0, new Date(body.retry_after).getTime() - Date.now()) + 250 : 2 ** attempt * 1000 await new Promise((r) => setTimeout(r, waitMs)) return bantaFetch(url, init, attempt + 1) } ``` If your integration consistently needs a higher rate, contact us at [support@banta.co.il](mailto:support@banta.co.il). --- # AI agents & MCP There are two ways to work with banta from AI tools: 1. **Let the agent read these docs** so it can write integration code against the API for you. See "Docs for AI agents" below. 2. **Connect the agent directly to your organization's data** through the banta MCP server, so it can search, summarize and take actions itself. See "Connecting over MCP". ## Docs for AI agents (LLM version) All of this documentation is also published as clean text that language models read easily, and it updates automatically with every API change. English (the default) lives at the site root; Hebrew lives under `/he/`. | English | Hebrew | Contents | |---|---|---| | [`/llms.txt`](https://docs.banta.co.il/llms.txt) | [`/he/llms.txt`](https://docs.banta.co.il/he/llms.txt) | Index following [llmstxt.org](https://llmstxt.org): a link to every guide and every endpoint | | [`/llms-full.txt`](https://docs.banta.co.il/llms-full.txt) | [`/he/llms-full.txt`](https://docs.banta.co.il/he/llms-full.txt) | The entire documentation in one file: guides and the full reference | | `/guides/.md` | `/he/guides/.md` | One guide as Markdown, e.g. [`/guides/authentication.md`](https://docs.banta.co.il/guides/authentication.md) | | `/reference/.md` | `/he/reference/.md` | One endpoint as Markdown, e.g. [`/reference/createLead.md`](https://docs.banta.co.il/reference/createLead.md) | | [`/openapi.json`](https://docs.banta.co.il/openapi.json) · [`/openapi.yaml`](https://docs.banta.co.il/openapi.yaml) | [`/he/openapi.json`](https://docs.banta.co.il/he/openapi.json) | The full OpenAPI document, for Postman, Insomnia or SDK generators | **On the site:** - **Ask AI** (top bar) - opens ChatGPT, Claude or Perplexity with an instruction to read `llms-full.txt`. - **Copy as Markdown** (on every endpoint) - copies that endpoint's documentation, ready to paste into a chat. **For coding agents (Claude Code, Cursor, Copilot)** - add this to your prompt or to your project's instructions file: ```text The banta API reference is at https://docs.banta.co.il/llms.txt (index) and https://docs.banta.co.il/llms-full.txt (full). Read it before writing integration code. Auth: header x-api-key. Base URL: https://app.banta.co.il/api-service ``` ## Connecting over MCP The banta MCP server gives AI agents tools for working with your organization's data: searching leads and files, summarizing a deal, creating tasks and reminders, and more. Server URL: ```text https://db.banta.co.il/functions/v1/mcp-server ``` ### Authentication - **OAuth (recommended)** - paste the URL into your MCP client. The client sends you to a banta sign-in and consent screen, and everything else is automatic. By default only organization admins can approve a connection. You can open this up to all members, or turn external connections off entirely, in [Organization settings → Integrations → AI](https://app.banta.co.il/organization/settings?group=integrations&tab=ai). - **Access token** - for clients that support custom headers. Create a token (it starts with `bnt_mcp_`) on the same settings screen and send it as `Authorization: Bearer `. ### Per client - **Claude (claude.ai and the Desktop app)** - Settings → Connectors → Add custom connector, paste the server URL and approve on the banta screen. - **Claude Code** - `claude mcp add --transport http banta https://db.banta.co.il/functions/v1/mcp-server` - **Cursor / VS Code** - the install button in the top bar of this site adds the server in one click. - **ChatGPT (GPT Actions)** - in Configure → Actions → Import from URL, import `https://db.banta.co.il/functions/v1/mcp-server/openapi.json`. Under Authentication choose API Key, type Bearer, and paste an access token. ### What an agent can do - The available tools are set by your organization's policy, and can be narrowed further per token. - Sensitive actions (money, status changes and deletions) may require approval by a user in the app. In that case the agent receives `approval_required`, and the action runs only after the request is approved in banta. - Every agent call is recorded in the organization's audit log. --- # Changelog Changes to the API, newest first. Breaking changes are marked **[Breaking]** and announced here in advance. ## October 2026 - The public documentation site launched at https://docs.banta.co.il in English and Hebrew, including an LLM version (`llms.txt`, `llms-full.txt` and Markdown per endpoint) and guides for authentication, permissions, pagination, errors and rate limits. - The OpenAPI document is now in English and was reconciled with actual behavior: consistent error responses (401/403/404/429/500) on every endpoint, and previously undocumented fields on charges and milestones. Tag names in the spec are now English (for example `Leads`). - `GET /api-docs/openapi.json` once again returns the full spec. It had been returning an outdated, abbreviated version. - **Security** - IDs sent in request bodies (`customer_id`, `lead_id`, `source_lead_id`, `parent_task_id`, `recipient_user_id`, `charge_id`) are validated against your organization. An ID that belongs to another organization returns 400. - **[Breaking] Permissions** - the general `write` permission no longer allows `DELETE`, matching the "Read & write" option in the app. Deleting requires `admin`, `resource:*` or `resource:delete`. - **Deletes** - `DELETE /mortgage-files/{id}` and `DELETE /customers/{id}` now delete the record. They previously returned success without deleting it. - **Statuses** - leads accept the organization's custom statuses. A new mortgage file gets the organization's default status (or `setup`) instead of the invalid `new`. `GET /mortgage-files/statuses` returns the real system statuses, `GET /mortgage-files/{id}/status-history` works, and a file status change saves `notes` as `status_comment`. A lead status change saves `notes` in the status history only and no longer overwrites the lead's notes. - **Tasks** - creating tasks works. Status values are `open`, `in_progress`, `completed` and `cancelled` (`done` is accepted as `completed`), and `completed_at` is set and cleared automatically. - **Notes** - a locked note can be unlocked with `is_locked: false`. - **Errors** - values the database rejects return 400 (duplicates return 409) instead of 500, and `child_errors` contains error codes only. - `GET /customers/{id}/mortgage-files` returns `{ data, count }` with the customer's mortgage files. ## August 2026 - **Charges** - a charge can be linked to a milestone with `milestone_id` and `milestone_status_key` (sent together), with an optional `milestone_due_offset_days`. When the milestone is completed, the due date is set automatically. A manually entered due date is never overwritten. - **Leads** - `DELETE /leads/{id}` permanently deletes the lead. A deleted lead cannot be restored. ## May 2026 - New endpoints nested under mortgage files: notes, file contacts, watchers, documents, signatures, generated documents, document statuses, reminders, charges, payments, analyses, calculator mixes, custom fields and milestones. - Top-level tasks (`/tasks`), linked to a file, a lead or a customer - or standalone. - Resource/action permissions (`leads:read` and so on) alongside the general ones. ## April 2026 - Security hardening: keys are stored hashed only, 401 responses explain the `reason`, a rate limit of 60 requests per minute per key, and list pages capped at 500. - An audit log entry for every write. ## January 2026 - Contacts (`/contacts`), system lists (`/lists`) and status endpoints for leads and files. - Incomes, bank accounts and obligations when creating a mortgage file, and more ID types for borrowers (passport, association, company). --- # banta API - **OpenAPI Version:** `3.2.0` - **API Version:** `1.0.0` - **Contact:** banta Support A REST API for managing your organization's data in banta: leads, customers, contacts, tasks, and mortgage files, including each file's sub-resources (borrowers, documents, charges, payments, milestones, and more). Every request authenticates with an API key in the `x-api-key` header, and all operations are scoped to the data of the organization that the key belongs to. Request and response bodies are JSON, and errors are returned in a consistent format (ErrorResponse). ## Servers - **URL:** `https://app.banta.co.il` - **Description:** Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). ## Tags ### Leads Inquiries from prospective customers: creation, updates, status changes, and permanent deletion ### Mortgage files Mortgage files: creation (including borrowers, incomes, and obligations), updates, status changes, and deletion ### Borrowers Borrowers on a mortgage file. Each borrower is linked to a customer record ### Customers The organization's customers: the people and entities who act as borrowers on files ### Contacts The organization's professional contacts: bankers, appraisers, lawyers, and more ### Lists Fixed system value lists (read-only): employment types, mortgage types, document statuses, and more ### Timeline Timeline events of a mortgage file (read-only) ### Tasks Tasks, linked to a file, lead, or customer, or standalone ### Notes Free-text notes on a mortgage file ### File contacts Linking the organization's contacts to a mortgage file ### Watchers Organization users who watch a mortgage file ### Documents The customer's documents in the file and the file's document requirements (read-only) ### Signatures Borrower signatures on the file's documents (read-only) ### Generated documents Documents generated from templates for the file (read-only) ### Document statuses Tracking the documents requested from the file's borrowers and updating their status ### Reminders Scheduled reminders on a mortgage file ### Charges Charges (payment requests) on a file, including links to milestones ### Payments Payments received on a file ### File analysis Saved analyses on a file (free-form JSON) ### Calculator mixes Mortgage mixes saved to the file from the calculator ### Custom fields Values of the custom fields the organization has defined for mortgage files ### Milestones The file's milestones: combined view, custom milestones, progress, and checklist items ## Operations ### List leads - **Method:** `GET` - **Path:** `/api-service/leads` - **Operation ID:** `getLeads` - **Tags:** Leads Returns the organization's leads (excluding deleted leads), newest first, with pagination. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` ##### `status` - **In:** `query` Filter by status. Leads with a custom status are stored with status=custom `string`, possible values: `"new", "contacted", "qualified", "converted", "lost", "custom"` ##### `search` - **In:** `query` Partial, case-insensitive search across first name, last name, phone, and email. The characters , ( ) % \_ \ " ' are stripped from the search term before searching. `string` #### Responses ##### Status: 200 List of leads ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `Lead` — A lead: an inquiry from a prospective customer. The response may include additional columns that are not documented here. - **`first_name` (required)** `string` — First name - **`last_name` (required)** `string` — Last name - **`phone` (required)** `string` — Phone number - **`additional_details`** `object` — Additional details (free-form structure) **Additional properties:** any (true schema) - **`assigned_to`** `string | null`, format: `uuid` — ID of the user the lead is assigned to (null if unassigned) - **`borrowers_data`** `array` — Details of the prospective borrowers **Items:** schema: `LeadBorrower` — Details of a prospective borrower on a lead - **`first_name` (required)** `string` — First name - **`last_name` (required)** `string` — Last name - **`birth_date`** `string`, format: `date` — Date of birth - **`email`** `string`, format: `email` — Email address - **`employment_type`** `string` — Employment type - **`id_number`** `string` — Israeli ID number - **`marital_status`** `string`, possible values: `"single", "married", "divorced", "widowed", "separated", "domestic_partnership", "other"` — Marital status - **`monthly_income`** `number` — Monthly income - **`phone`** `string` — Phone number - **`relationship_type`** `string`, possible values: `"main", "spouse", "business_partner", "co_borrower", "guarantor", "siblings", "other"` — Relationship type - **`converted_to_customer`** `string`, format: `uuid` — ID of the customer the lead was converted to (if converted) - **`converted_to_mortgage_file_id`** `string`, format: `uuid` — ID of the mortgage file created from the lead (if converted) - **`created_at`** `string`, format: `date-time` — Creation date - **`created_by`** `string`, format: `uuid` — ID of the user who created the lead - **`custom_fields_leads`** `object` — Custom fields defined by the organization **Additional properties:** any (true schema) - **`email`** `string`, format: `email` — Email address - **`financial_data`** `object` — Financial details - **`existing_obligations`** `number` — Existing obligations - **`monthly_income`** `number` — Monthly income - **`savings`** `number` — Savings - **`first_response_time`** `string`, format: `date-time` — Time of the first response to the lead - **`has_property`** `boolean` — Whether the lead already owns a property - **`id`** `string`, format: `uuid` — Lead ID - **`landing_path`** `string` — Path of the landing page where the lead was captured - **`lead_number`** `string` — Unique lead number (generated automatically) - **`mortgage_purpose`** `string` — Mortgage purpose (purchase, refinance, renovation, etc.) - **`mortgage_request_data`** `object` — Mortgage request details - **`loan_purpose`** `string` — Loan purpose - **`property_location`** `string` — Property location - **`property_type`** `string` — Property type - **`property_value`** `number` — Property value - **`notes`** `string` — General notes - **`organization_id`** `string`, format: `uuid` — Organization ID - **`referrer_url`** `string` — Referrer URL the lead came from - **`required_amount`** `number` — Required mortgage amount - **`source`** `string` — Lead source. A lead created through the API without a source gets the value api - **`status`** `string`, possible values: `"new", "contacted", "qualified", "converted", "lost", "custom"` — Lead status. custom indicates one of the organization's custom statuses, whose key is stored in status_custom - **`status_changed_at`** `string`, format: `date-time` — Date of the last status change - **`status_custom`** `string | null` — Key of the custom status (when status=custom) - **`team_id`** `string`, format: `uuid` — ID of the team the lead belongs to - **`total_income`** `number` — Total monthly income of all borrowers - **`updated_at`** `string`, format: `date-time` — Last updated date - **`utm_campaign`** `string` — The utm_campaign parameter captured with the lead - **`utm_content`** `string` — The utm_content parameter captured with the lead - **`utm_medium`** `string` — The utm_medium parameter captured with the lead - **`utm_source`** `string` — The utm_source parameter captured with the lead - **`utm_term`** `string` — The utm_term parameter captured with the lead **Example:** ```json { "data": [ { "id": "", "organization_id": "", "lead_number": "", "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "new", "status_custom": null, "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null, "team_id": "", "borrowers_data": [ { "first_name": "", "last_name": "", "id_number": "", "phone": "", "email": "", "birth_date": "", "relationship_type": "main", "marital_status": "single", "employment_type": "", "monthly_income": 1 } ], "mortgage_request_data": { "property_type": "", "property_value": 1, "property_location": "", "loan_purpose": "" }, "financial_data": { "monthly_income": 1, "existing_obligations": 1, "savings": 1 }, "additional_details": { "additionalProperty": "anything" }, "custom_fields_leads": { "additionalProperty": "anything" }, "converted_to_customer": "", "converted_to_mortgage_file_id": "", "utm_source": "", "utm_medium": "", "utm_campaign": "", "utm_term": "", "utm_content": "", "referrer_url": "", "landing_path": "", "status_changed_at": "", "first_response_time": "", "created_at": "", "updated_at": "", "created_by": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a lead - **Method:** `POST` - **Path:** `/api-service/leads` - **Operation ID:** `createLead` - **Tags:** Leads Creates a new lead in the organization. - Required: first_name, last_name, and phone (non-empty values). A missing field returns 400, and the missing fields are listed in validation. - Defaults: status=new, source=api, has_property=false. - status - a system status or one of the organization's custom statuses (see GET /leads/statuses); any other value returns 400. - An assigned_to value that is not the ID of an active user in the organization is ignored, and the lead is created unassigned. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Request Body Details of the new lead **Required:** `true` ##### Content-Type: application/json schema: `CreateLead` — Data for creating a lead. Fields not listed here are ignored. - **`first_name` (required)** `string` — First name - **`last_name` (required)** `string` — Last name - **`phone` (required)** `string` — Phone number - **`assigned_to`** `string`, format: `uuid` — ID of a user in the organization to assign the lead to. An ID that does not belong to an active user in the organization is ignored, and the lead is created unassigned - **`email`** `string`, format: `email` — Email address - **`has_property`** `boolean`, default: `false` — Whether the lead already owns a property - **`mortgage_purpose`** `string` — Mortgage purpose (purchase, refinance, renovation, etc.) - **`notes`** `string` — General notes - **`required_amount`** `number` — Required mortgage amount - **`source`** `string`, default: `"api"` — Lead source (for example website, facebook, referral) - **`status`** `string`, default: `"new"` — Initial status: a system status or one of the organization's custom statuses (see GET /leads/statuses) - **`total_income`** `number` — Total monthly income of all borrowers **Example: default** ```json { "first_name": "Dana", "last_name": "Levi", "phone": "050-0000000", "email": "dana.levi@example.com", "source": "website", "mortgage_purpose": "Second-hand apartment purchase", "required_amount": 1200000, "total_income": 28000, "has_property": false, "notes": "Prefers a call after 17:00" } ``` #### Responses ##### Status: 201 The lead was created ###### Content-Type: application/json *Schema `Lead` is shown above.* **Example: default** ```json { "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b", "organization_id": "0b8e1f2a-7c3d-4a5b-9e6f-2a3b4c5d6e7f", "first_name": "Dana", "last_name": "Levi", "email": "dana.levi@example.com", "phone": "050-0000000", "source": "website", "status": "new", "status_custom": null, "notes": "Prefers a call after 17:00", "mortgage_purpose": "Second-hand apartment purchase", "required_amount": 1200000, "total_income": 28000, "has_property": false, "assigned_to": null, "created_at": "2026-10-14T08:15:22.481234+00:00", "updated_at": "2026-10-14T08:15:22.481234+00:00" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a lead - **Method:** `GET` - **Path:** `/api-service/leads/{id}` - **Operation ID:** `getLeadById` - **Tags:** Leads Returns a lead by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Lead ID `string`, format: `uuid` #### Responses ##### Status: 200 Lead details ###### Content-Type: application/json *Schema `Lead` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "lead_number": "", "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "new", "status_custom": null, "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null, "team_id": "", "borrowers_data": [ { "first_name": "", "last_name": "", "id_number": "", "phone": "", "email": "", "birth_date": "", "relationship_type": "main", "marital_status": "single", "employment_type": "", "monthly_income": 1 } ], "mortgage_request_data": { "property_type": "", "property_value": 1, "property_location": "", "loan_purpose": "" }, "financial_data": { "monthly_income": 1, "existing_obligations": 1, "savings": 1 }, "additional_details": { "additionalProperty": "anything" }, "custom_fields_leads": { "additionalProperty": "anything" }, "converted_to_customer": "", "converted_to_mortgage_file_id": "", "utm_source": "", "utm_medium": "", "utm_campaign": "", "utm_term": "", "utm_content": "", "referrer_url": "", "landing_path": "", "status_changed_at": "", "first_response_time": "", "created_at": "", "updated_at": "", "created_by": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a lead - **Method:** `PUT` - **Path:** `/api-service/leads/{id}` - **Operation ID:** `updateLead` - **Tags:** Leads Partially updates a lead: only the fields sent are updated (PUT and PATCH are identical). If no updatable field is sent, returns 400. assigned_to=null (or an empty string) removes the assignment; an ID that does not belong to an active user in the organization is ignored. To change the status and record the change in the lead's status history, use PATCH /leads/{id}/status. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Lead ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateLead` — Partial update of a lead: only the fields sent are updated. Fields not listed here are ignored. - **`assigned_to`** `string | null`, format: `uuid` — ID of a user in the organization. null or an empty string removes the assignment; an ID that does not belong to an active user in the organization is ignored - **`email`** `string`, format: `email` — Email address - **`first_name`** `string` — First name - **`has_property`** `boolean` — Whether the lead already owns a property - **`last_name`** `string` — Last name - **`mortgage_purpose`** `string` — Mortgage purpose (purchase, refinance, renovation, etc.) - **`notes`** `string` — General notes - **`phone`** `string` — Phone number - **`required_amount`** `number` — Required mortgage amount - **`source`** `string` — Lead source - **`status`** `string` — Lead status: a system status or one of the organization's custom statuses (see GET /leads/statuses). For a status change that is recorded in the status history, use PATCH /leads/{id}/status - **`total_income`** `number` — Total monthly income of all borrowers **Example:** ```json { "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "", "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null } ``` #### Responses ##### Status: 200 The updated lead ###### Content-Type: application/json *Schema `Lead` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "lead_number": "", "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "new", "status_custom": null, "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null, "team_id": "", "borrowers_data": [ { "first_name": "", "last_name": "", "id_number": "", "phone": "", "email": "", "birth_date": "", "relationship_type": "main", "marital_status": "single", "employment_type": "", "monthly_income": 1 } ], "mortgage_request_data": { "property_type": "", "property_value": 1, "property_location": "", "loan_purpose": "" }, "financial_data": { "monthly_income": 1, "existing_obligations": 1, "savings": 1 }, "additional_details": { "additionalProperty": "anything" }, "custom_fields_leads": { "additionalProperty": "anything" }, "converted_to_customer": "", "converted_to_mortgage_file_id": "", "utm_source": "", "utm_medium": "", "utm_campaign": "", "utm_term": "", "utm_content": "", "referrer_url": "", "landing_path": "", "status_changed_at": "", "first_response_time": "", "created_at": "", "updated_at": "", "created_by": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a lead - **Method:** `PATCH` - **Path:** `/api-service/leads/{id}` - **Operation ID:** `patchLead` - **Tags:** Leads Partially updates a lead: only the fields sent are updated (PUT and PATCH are identical). If no updatable field is sent, returns 400. assigned_to=null (or an empty string) removes the assignment; an ID that does not belong to an active user in the organization is ignored. To change the status and record the change in the lead's status history, use PATCH /leads/{id}/status. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Lead ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateLead` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "", "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null } ``` #### Responses ##### Status: 200 The updated lead ###### Content-Type: application/json *Schema `Lead` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "lead_number": "", "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "new", "status_custom": null, "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null, "team_id": "", "borrowers_data": [ { "first_name": "", "last_name": "", "id_number": "", "phone": "", "email": "", "birth_date": "", "relationship_type": "main", "marital_status": "single", "employment_type": "", "monthly_income": 1 } ], "mortgage_request_data": { "property_type": "", "property_value": 1, "property_location": "", "loan_purpose": "" }, "financial_data": { "monthly_income": 1, "existing_obligations": 1, "savings": 1 }, "additional_details": { "additionalProperty": "anything" }, "custom_fields_leads": { "additionalProperty": "anything" }, "converted_to_customer": "", "converted_to_mortgage_file_id": "", "utm_source": "", "utm_medium": "", "utm_campaign": "", "utm_term": "", "utm_content": "", "referrer_url": "", "landing_path": "", "status_changed_at": "", "first_response_time": "", "created_at": "", "updated_at": "", "created_by": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Permanently delete a lead - **Method:** `DELETE` - **Path:** `/api-service/leads/{id}` - **Operation ID:** `deleteLead` - **Tags:** Leads Deletes the lead **permanently** (hard delete). This action cannot be undone: leads have no recycle bin. Records that depend solely on the lead are deleted along with it, while records that can exist without it (for example, a mortgage file created from the lead) are kept and unlinked from it. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Lead ID `string`, format: `uuid` #### Responses ##### Status: 200 The lead was permanently deleted ###### Content-Type: application/json schema: `DeleteResult` — Deletion result - **`message` (required)** `string` — Confirmation message (in English) - **`success` (required)** `boolean` **Example: default** ```json { "success": true, "message": "Lead permanently deleted" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a lead's status - **Method:** `PATCH` - **Path:** `/api-service/leads/{id}/status` - **Operation ID:** `updateLeadStatus` - **Tags:** Leads Changes the lead's status, updates status_changed_at, and records the change in the lead's status history. status can be a system status (new, contacted, qualified, converted, lost) or one of the organization's custom statuses (the value field in GET /leads/statuses); a custom status is stored as status=custom with its key in status_custom. Any other value returns 400. notes (optional) is saved in the status history only. A missing status returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Lead ID `string`, format: `uuid` #### Request Body The new status **Required:** `true` ##### Content-Type: application/json - **`status` (required)** `string` — The new status: a system status or one of the organization's custom statuses (see GET /leads/statuses) - **`notes`** `string` — A note on the status change, saved in the status history **Example: default** ```json { "status": "contacted", "notes": "First call completed, meeting scheduled" } ``` #### Responses ##### Status: 200 The lead after the status update ###### Content-Type: application/json *Schema `Lead` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "lead_number": "", "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "new", "status_custom": null, "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null, "team_id": "", "borrowers_data": [ { "first_name": "", "last_name": "", "id_number": "", "phone": "", "email": "", "birth_date": "", "relationship_type": "main", "marital_status": "single", "employment_type": "", "monthly_income": 1 } ], "mortgage_request_data": { "property_type": "", "property_value": 1, "property_location": "", "loan_purpose": "" }, "financial_data": { "monthly_income": 1, "existing_obligations": 1, "savings": 1 }, "additional_details": { "additionalProperty": "anything" }, "custom_fields_leads": { "additionalProperty": "anything" }, "converted_to_customer": "", "converted_to_mortgage_file_id": "", "utm_source": "", "utm_medium": "", "utm_campaign": "", "utm_term": "", "utm_content": "", "referrer_url": "", "landing_path": "", "status_changed_at": "", "first_response_time": "", "created_at": "", "updated_at": "", "created_by": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List lead statuses - **Method:** `GET` - **Path:** `/api-service/leads/statuses` - **Operation ID:** `getLeadStatuses` - **Tags:** Leads Returns the organization's lead status configuration. If the organization has defined its own statuses, source=custom and the items are the organization's stored definitions (their structure may differ from the default). Otherwise, source=default and the items are the system statuses. Use the value field of an item as status in POST /leads, PUT/PATCH /leads/{id} and PATCH /leads/{id}/status. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Lead statuses ###### Content-Type: application/json - **`count`** `integer` — Number of items in the data array - **`data`** `array` — List of statuses **Items:** schema: `LeadStatus` — A lead status, including the organization's custom statuses - **`color`** `object` - **`bg`** `string` — Background color (HEX) - **`text`** `string` — Text color (HEX) - **`is_default`** `boolean` — Whether this is the default status - **`label`** `string` — Display name in Hebrew - **`value`** `string` — Status identifier (key) - **`source`** `string`, possible values: `"default", "custom"` — Source of the list: the organization's configuration (custom) or the default (default) **Example: default** ```json { "data": [ { "value": "new", "label": "חדש", "color": { "bg": "#3498db", "text": "#ffffff" }, "is_default": true }, { "value": "contacted", "label": "נוצר קשר", "color": { "bg": "#f39c12", "text": "#ffffff" }, "is_default": false }, { "value": "qualified", "label": "מתאים", "color": { "bg": "#2ecc71", "text": "#ffffff" }, "is_default": false }, { "value": "converted", "label": "הומר ללקוח", "color": { "bg": "#1abc9c", "text": "#ffffff" }, "is_default": false }, { "value": "lost", "label": "אבוד", "color": { "bg": "#e74c3c", "text": "#ffffff" }, "is_default": false } ], "count": 5, "source": "default" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List mortgage files - **Method:** `GET` - **Path:** `/api-service/mortgage-files` - **Operation ID:** `getMortgageFiles` - **Tags:** Mortgage files Returns the organization's mortgage files (excluding deleted files), newest first, with pagination. Each file includes the borrowers array, which holds the file's active borrowers. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` ##### `status` - **In:** `query` Filter by status key (see GET /mortgage-files/statuses) `string` ##### `customer_id` - **In:** `query` Filter to a customer's files (the file's primary customer) `string`, format: `uuid` ##### `search` - **In:** `query` Partial, case-insensitive search across the file number and title. The characters , ( ) % \_ \ " ' are stripped from the search term before searching. `string` #### Responses ##### Status: 200 List of mortgage files ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** **All of:** schema: `MortgageFile` — A mortgage file (the file record). The response may include additional internal columns that are not documented here. - **`additional_expenses`** `array` — Additional expenses (taxes, legal fees, brokerage fees, etc.) **Items:** schema: `AdditionalExpense` — An additional expense associated with the transaction - **`amount` (required)** `number` — Expense amount - **`type` (required)** `string` — Expense type (purchase tax, legal fees, brokerage fees, etc.) - **`description`** `string` — Additional description - **`additional_info`** `object` — Extended additional information **All of:** schema: `MortgageAdditionalInfo` — Additional information about a mortgage file - **`general_notes`** `string` — General notes - **`important_info`** `object` — Important information - **`credit_report_status`** `string` — Credit report status - **`equity_sources`** `string` — Sources of equity - **`financial_issues_details`** `string` — Details of the financial issues - **`grace_period_months`** `integer` — Length of the grace period in months - **`has_financial_issues`** `boolean` — Whether there are financial issues - **`has_grace_period`** `boolean` — Whether there is a grace period - **`payment_day`** `integer` — Day of the month on which payments are made - **`requested_monthly_payment`** `number` — Requested monthly repayment - **`appraiser_value`** `number` — Property value according to the appraiser - **`assigned_to`** `string | null`, format: `uuid` — ID of the user the file is assigned to (null if unassigned) - **`contract_date_payment`** `string` — Payment date under the contract - **`created_at`** `string`, format: `date-time` — Creation date - **`created_by`** `string`, format: `uuid` — ID of the user who created the file - **`custom_fields_mortgage`** `object` — Custom fields defined by the organization **Additional properties:** any (true schema) - **`customer_id`** `string`, format: `uuid` — ID of the file's primary customer - **`drive_folder_url`** `string` — Link to the Google Drive folder - **`eligibility`** `number` — Eligibility amount (if applicable) - **`equity`** `number` — Equity - **`file_number`** `string` — File number - **`financing_entity`** `object` — Financing entity details (bank) **All of:** schema: `FinancingEntity` — Financing entity details (bank) - **`bank_name`** `string` — Bank name - **`branch_name`** `string` — Branch name - **`branch_number`** `string` — Branch number - **`contact_email`** `string`, format: `email` — Contact person's email address - **`contact_name`** `string` — Name of the contact person at the bank - **`contact_phone`** `string` — Contact person's phone number - **`id`** `string`, format: `uuid` — File ID - **`interest_rate`** `number` — Average interest rate - **`lead_id`** `string`, format: `uuid` — ID of a linked lead - **`lead_source`** `string` — Source of the lead that became this file - **`loan_amount`** `number` — Requested mortgage amount - **`loan_purpose`** `string` — Loan purpose - **`loan_term`** `integer` — Loan term in months - **`monthly_payment`** `number` — Expected monthly repayment - **`notes`** `string` — General notes - **`organization_id`** `string`, format: `uuid` — Organization ID - **`property_address`** `string` — Full property address - **`property_type`** `string` — Property type (apartment, private house, plot, etc.) - **`property_value`** `number` — Property value per the contract/valuation - **`purposes`** `array` — Mortgage purposes **Items:** schema: `MortgagePurpose` — A mortgage purpose (purchase, refinance, renovation, etc.) - **`amount` (required)** `number` — Amount required for this purpose - **`type` (required)** `string` — Purpose type - a key from the GET /lists/mortgage-types list (for example second_hand, refinance) - **`details`** `string` — Additional details about the purpose - **`fields`** `object` — Detailed fields, depending on the purpose type - **`appraiser_value`** `number` — Property value according to the appraiser - **`contract_date_payment`** `string` — Payment date under the contract - **`eligibility`** `number` — Eligibility amount - **`equity`** `number` — Equity - **`equity_amount`** `number` — Equity amount - **`existing_mortgage`** `number` — Outstanding balance of the existing mortgage - **`loan_amount`** `number` — Requested mortgage amount - **`loan_purpose`** `string` — Detailed loan purpose - **`monthly_repayment`** `number` — Monthly repayment - **`mortgage_type`** `string` — Mortgage type - **`property_value`** `number` — Property value - **`requested_mortgage`** `number` — Requested mortgage - **`required_date`** `string` — Date by which the mortgage is needed - **`tax_declaration`** `string` — Real estate tax (Mas Shevach) declaration: single apartment, replacement apartment or investment apartment. Values: \`GET /api-service/lists/mishach-types\` - **`real_estate_details`** `object` — Extended real estate details **Additional properties:** any (true schema) - **`remaining_mortgage`** `number` — Outstanding balance of the existing mortgage (for refinancing) - **`source_lead_id`** `string`, format: `uuid` — ID of the original lead (if converted from a lead) - **`source_lead_number`** `string` — Number of the original lead - **`status`** `string` — Key of the file's status: one of the system statuses (setup, pending_approval, pending_appraisal, reviewing, signing, completed, paused, cancelled, active) or a custom status defined by the organization. See GET /mortgage-files/statuses - **`status_changed_at`** `string`, format: `date-time` — Date of the last status change - **`status_comment`** `string` — Comment on the current status - **`tax_declaration`** `string` — Real estate tax (Mas Shevach) declaration: single apartment, replacement apartment or investment apartment. Values: \`GET /api-service/lists/mishach-types\` - **`title`** `string` — File title/name - **`total_amount`** `number` — Total transaction amount - **`updated_at`** `string`, format: `date-time` — Last updated date * **`borrowers`** `array` — The file's active borrowers **Items:** schema: `Borrower` — A borrower on a mortgage file: the record that links a customer to the file (relationship type, order, borrower type), together with the linked customer's details. Customer details (name, identification, contact details, etc.) are stored on the customer record and shared across all files in which that customer is a borrower. - **`birth_date`** `string`, format: `date` — Date of birth - **`borrower_type`** `string`, possible values: `"regular", "paying_guarantor", "supporting_guarantor", "non_mortgaging_borrower"` — Borrower type - **`children_birth_dates`** `array` — Children's dates of birth **Items:** `string`, format: `date` - **`children_under_18`** `integer` — Number of children under 18 - **`city`** `string` — City of residence - **`created_at`** `string`, format: `date-time` — Creation date - **`custom_marital_status`** `string` — Custom marital status (when marital_status=other) - **`custom_relationship`** `string` — Custom relationship type (when relationship_type=other) - **`customer_id`** `string`, format: `uuid` — ID of the linked customer - **`email`** `string`, format: `email` — Email address - **`entity_name`** `string` — Name of the company or nonprofit association (when id_type is company or association) - **`first_name`** `string` — First name - **`foreign_citizenship`** `string` — Country of foreign citizenship - **`gender`** `string`, possible values: `"male", "female", "other"` — Gender - **`has_children`** `boolean` — Whether the borrower has children - **`has_foreign_citizenship`** `boolean` — Whether the borrower holds foreign citizenship - **`id`** `string`, format: `uuid` — Borrower ID (the record linking the customer to the file) - **`id_country`** `string` — Country that issued the identification document (relevant for passports) - **`id_expiry_date`** `string`, format: `date` — Expiration date of the identification document - **`id_number`** `string` — Identification document number - **`id_type`** `string`, possible values: `"israeli_id", "passport", "association", "company"` — Identification document type - **`is_politically_exposed`** `boolean` — Whether the borrower is a politically exposed person (PEP) - **`issue_date`** `string`, format: `date` — Issue date of the identification document - **`last_name`** `string` — Last name - **`marital_status`** `string`, possible values: `"single", "married", "divorced", "widowed", "separated", "domestic_partnership", "other"` — Marital status - **`mortgage_file_id`** `string`, format: `uuid` — Mortgage file ID - **`order_index`** `integer` — The borrower's position on the file (0 = main borrower) - **`organization_id`** `string`, format: `uuid` — Organization ID - **`phone`** `string` — Phone number - **`preferred_contact_methods`** `array` — Preferred contact methods **Items:** `string`, possible values: `"email", "sms", "whatsapp", "voice", "no_sms"` - **`relationship_type`** `string`, possible values: `"main", "spouse", "business_partner", "siblings", "other"` — The borrower's relationship type on the file. A borrower with order_index=0 must be main - **`spouse_of_borrower_id`** `string`, format: `uuid` — ID of the borrower who is this borrower's spouse (in files with more than 2 borrowers) - **`street`** `string` — Street of residence - **`updated_at`** `string`, format: `date-time` — Last updated date schema: `MortgageFileDetails` — A mortgage file together with its active borrowers **Example:** ```json { "data": [ { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "", "borrowers": [ { "id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "spouse_of_borrower_id": "", "customer_id": "", "order_index": 1, "mortgage_file_id": "", "organization_id": "", "created_at": "", "updated_at": "" } ] } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a mortgage file - **Method:** `POST` - **Path:** `/api-service/mortgage-files` - **Operation ID:** `createMortgageFile` - **Tags:** Mortgage files Creates a new mortgage file and, optionally, in the same request, its borrowers, incomes, bank accounts, and obligations. No fields are required. - **status** - If omitted, the organization's default status is used (set in the app's mortgage status settings), or `setup` if none is set. A value you send must be a valid status in the organization: one of the system statuses (setup, pending_approval, pending_appraisal, reviewing, signing, completed, paused, cancelled, active) or a custom status defined by the organization (see GET /mortgage-files/statuses). Otherwise the API returns 400 (code 23514). - **customer_id / lead_id / source_lead_id** - Must be IDs of active records in the organization; otherwise the API returns 400. - **file_number** - The API does not assign a file number automatically. - **assigned_to** - An ID that does not belong to an active user in the organization is ignored, and the mortgage file is created unassigned. - **borrowers** - Each borrower is created as in POST /mortgage-files/{id}/borrowers (an existing customer is matched by id_number, or a new customer is created). The first borrower defaults to relationship_type=main, and subsequent borrowers default to spouse. - **incomes / bank_accounts / obligations** - Saved as sent. A failure to create a borrower or to save incomes, bank accounts, or obligations does not roll back the creation of the mortgage file: the response is 201, and the failures are listed in the child_errors array. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Request Body Details of the new mortgage file **Required:** `true` ##### Content-Type: application/json schema: `CreateMortgageFile` — Data for creating a mortgage file. No fields are required. Fields not listed here are ignored. - **`additional_expenses`** `array` — Additional expenses **Items:** *Schema `AdditionalExpense` is shown above.* - **`additional_info`** `object` — Extended additional information **All of:** *Schema `MortgageAdditionalInfo` is shown above.* - **`appraiser_value`** `number` — Property value according to the appraiser - **`assigned_to`** `string`, format: `uuid` — ID of a user in the organization to assign the file to. An ID that does not belong to an active user in the organization is ignored, and the file is created unassigned - **`bank_accounts`** `array` — The borrowers' bank accounts. Stored as sent **Items:** schema: `BankAccount` — A bank account - **`accountNumber` (required)** `string` — Account number - **`bankName` (required)** `string` — Bank name (code) - **`branchName` (required)** `string` — Branch number - **`bankDisplayName`** `string` — Bank display name - **`borrowers`** `array` — IDs/names of the borrowers associated with the account **Items:** `string` - **`branchDisplayName`** `string` — Branch name - **`isJoint`** `boolean` — Whether this is a joint account - **`borrowers`** `array` — Borrowers to create together with the file. Each item is handled like POST /mortgage-files/{id}/borrowers; the first defaults to relationship_type=main and the rest to spouse **Items:** schema: `CreateBorrower` — Data for adding a borrower to a file. Customer fields (name, identification, contact details, etc.) are saved to the customer record, and only when id_number is sent - see the description of the POST /mortgage-files/{id}/borrowers operation. - **`birth_date`** `string`, format: `date` — Date of birth - **`borrower_type`** `string`, possible values: `"regular", "paying_guarantor", "supporting_guarantor", "non_mortgaging_borrower"`, default: `"regular"` — Borrower type - **`children_birth_dates`** `array` — Children's dates of birth **Items:** `string`, format: `date` - **`children_under_18`** `integer` — Number of children under 18 - **`city`** `string` — City of residence - **`custom_marital_status`** `string` — Custom marital status (when marital_status=other) - **`custom_relationship`** `string` — Custom relationship type (when relationship_type=other) - **`customer_id`** `string`, format: `uuid` — ID of an existing customer to link. Used only when id_number is not sent - **`email`** `string`, format: `email` — Email address - **`entity_name`** `string` — Name of the company or nonprofit association (when id_type is company or association) - **`first_name`** `string` — First name (required when a new customer is created) - **`foreign_citizenship`** `string` — Country of foreign citizenship - **`gender`** `string`, possible values: `"male", "female", "other"` — Gender - **`has_children`** `boolean` — Whether the borrower has children - **`has_foreign_citizenship`** `boolean` — Whether the borrower holds foreign citizenship - **`id_country`** `string` — Country that issued the identification document (relevant for passports) - **`id_expiry_date`** `string`, format: `date` — Expiration date of the identification document - **`id_number`** `string` — Identification document number. Used to find an existing customer in the organization or to create a new customer - **`id_type`** `string`, possible values: `"israeli_id", "passport", "association", "company"` — Identification document type. For a new customer, defaults to israeli_id - **`is_politically_exposed`** `boolean` — Whether the borrower is a politically exposed person (PEP) - **`issue_date`** `string`, format: `date` — Issue date of the identification document - **`last_name`** `string` — Last name (required when a new customer is created) - **`marital_status`** `string`, possible values: `"single", "married", "divorced", "widowed", "separated", "domestic_partnership", "other"` — Marital status - **`order_index`** `integer` — The borrower's position on the file (0 = main borrower). Default: the number of borrowers already on the file - **`phone`** `string` — Phone number - **`preferred_contact_methods`** `array` — Preferred contact methods **Items:** `string`, possible values: `"email", "sms", "whatsapp", "voice", "no_sms"` - **`relationship_type`** `string`, possible values: `"main", "spouse", "business_partner", "siblings", "other"` — Relationship type on the file. Default: main for the first borrower on the file, spouse for subsequent borrowers. A borrower with order_index=0 must be main - **`street`** `string` — Street of residence - **`contract_date_payment`** `string` — Payment date under the contract - **`custom_fields_mortgage`** `object` — Custom fields **Additional properties:** any (true schema) - **`customer_id`** `string`, format: `uuid` — ID of the file's primary customer (optional) - **`eligibility`** `number` — Eligibility amount - **`equity`** `number` — Equity - **`file_number`** `string` — File number. The API does not assign a number automatically - if omitted, the file is created without a number - **`financing_entity`** `object` — Financing entity details (bank) **All of:** *Schema `FinancingEntity` is shown above.* - **`incomes`** `object` — The borrowers' income data. Stored as sent **All of:** schema: `Incomes` — Income data for a mortgage file - **`borrowers`** `array` — Income by borrower **Items:** schema: `BorrowerIncome` — A borrower's income data - **`borrowerId`** `string`, format: `uuid` — Borrower ID - **`borrowerName`** `string` — Borrower name - **`employments`** `array` — List of employment/income sources **Items:** schema: `EmploymentItem` — An employment/income item - **`data`** `object` — Employment details, depending on the type - **`amount`** `string` — Amount - **`average_monthly_income`** `string` — Average monthly income - **`business_name`** `string` — Business name (for self-employed) - **`business_type`** `string` — Business type - **`description`** `string` — Description (for other income) - **`employers`** `array` — List of employers (for salaried employees) **Items:** - **`company_name`** `string` — Company name - **`end_date`** `string`, format: `date` — Employment end date - **`is_current`** `boolean` — Whether this is the current employer - **`position`** `string` — Job title - **`salary_slips`** `array` — Pay slips **Items:** - **`amount`** `string` — Amount - **`date`** `string` — Pay slip date - **`start_date`** `string`, format: `date` — Employment start date - **`institution`** `string` — Institution awarding the scholarship - **`is_controlling_employee`** `boolean` — Whether the employee is a controlling shareholder - **`is_public_sector`** `boolean` — Whether the employer is in the public sector - **`monthly_amount`** `string` — Monthly amount (for a pension/allowance) - **`scholarship_amount`** `string` — Scholarship amount - **`source`** `string` — Income source - **`years_active`** `number` — Years in business - **`type`** `string`, possible values: `"salaried", "self_employed", "pension", "allowance", "scholarship", "other", "unemployed"` — Employment type (salaried employee, self-employed, pension, allowance, scholarship, other, not employed) - **`interest_rate`** `number` — Average interest rate - **`lead_id`** `string`, format: `uuid` — ID of a linked lead - **`lead_source`** `string` — Lead source - **`loan_amount`** `number` — Requested mortgage amount - **`loan_purpose`** `string` — Loan purpose - **`loan_term`** `integer` — Loan term in months - **`monthly_payment`** `number` — Expected monthly repayment - **`notes`** `string` — General notes - **`obligations`** `array` — The borrowers' financial obligations. Stored as sent **Items:** schema: `Obligation` — A financial obligation - **`monthlyPayment` (required)** `number` — Monthly payment - **`type` (required)** `string`, possible values: `"bank_loan", "non_bank_loan", "mortgage", "alimony", "rent", "other"` — Obligation type (bank loan, non-bank loan, mortgage, alimony, rent, other) - **`assignedBorrowers`** `array` — IDs of the borrowers the obligation belongs to **Items:** `string` - **`bank_id`** `string` — Bank ID (for bank loans) - **`bankData`** `object` — Bank details - **`accountNumber`** `string` — Account number - **`bankDisplayName`** `string` — Bank name - **`bankName`** `string` — Bank code - **`branchDisplayName`** `string` — Branch name - **`branchName`** `string` — Branch number - **`customType`** `string` — Custom type (when type=other) - **`endDate`** `string`, format: `date` — End date - **`id`** `string` — Unique obligation ID - **`remainingAmount`** `number` — Outstanding balance - **`property_address`** `string` — Full property address - **`property_type`** `string` — Property type (apartment, private house, plot, etc.) - **`property_value`** `number` — Property value - **`purposes`** `array` — Mortgage purposes (default: an empty array) **Items:** *Schema `MortgagePurpose` is shown above.* - **`real_estate_details`** `object` — Extended real estate details **Additional properties:** any (true schema) - **`remaining_mortgage`** `number` — Outstanding balance of the existing mortgage (for refinancing) - **`source_lead_id`** `string`, format: `uuid` — ID of the original lead the file was created from - **`source_lead_number`** `string` — Number of the original lead - **`status`** `string`, default: `"new"` — A valid status key in the organization (a system status or a custom status). If omitted, the API sets new - see the operation description - **`status_comment`** `string` — Comment on the current status - **`tax_declaration`** `string` — Real estate tax (Mas Shevach) declaration: single apartment, replacement apartment or investment apartment. Values: \`GET /api-service/lists/mishach-types\` - **`title`** `string` — File title/name - **`total_amount`** `number` — Total transaction amount **Example: default** ```json { "file_number": "2026-0042", "title": "Apartment purchase - Cohen family", "status": "setup", "customer_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "purposes": [ { "type": "second_hand", "amount": 1200000 } ], "loan_amount": 1200000, "property_type": "apartment", "property_value": 2000000, "property_address": "10 Herzl St., Ramat Gan", "equity": 800000, "borrowers": [ { "first_name": "Yossi", "last_name": "Cohen", "id_number": "000000018", "phone": "052-0000000", "email": "yossi.cohen@example.com", "relationship_type": "main" }, { "first_name": "Ronit", "last_name": "Cohen", "id_number": "000000026", "phone": "054-0000000", "relationship_type": "spouse" } ], "incomes": { "borrowers": [ { "borrowerName": "Yossi Cohen", "employments": [ { "type": "salaried", "data": { "employers": [ { "company_name": "Example Company Ltd.", "position": "Engineer", "start_date": "2019-01-01", "is_current": true } ] } } ] } ] }, "bank_accounts": [ { "bankName": "12", "bankDisplayName": "Example Bank", "branchName": "600", "branchDisplayName": "Central Branch", "accountNumber": "123456", "isJoint": true } ], "obligations": [ { "type": "bank_loan", "monthlyPayment": 1500, "remainingAmount": 30000, "endDate": "2027-12-31" } ] } ``` #### Responses ##### Status: 201 Mortgage file created ###### Content-Type: application/json **All of:** *Schema `MortgageFile` is shown above.* - **`bank_accounts`** `array | null` — The saved bank accounts, or null **Items:** *Schema `BankAccount` is shown above.* - **`borrowers`** `array` — The borrower link records that were created, without customer details. For full details, retrieve the file or /borrowers **Items:** schema: `BorrowerBase` — A borrower's link record to a file, without customer details - **`borrower_type`** `string | null`, possible values: `"regular", "paying_guarantor", "supporting_guarantor", "non_mortgaging_borrower"` - **`created_at`** `string`, format: `date-time` - **`custom_relationship`** `string | null` - **`customer_id`** `string | null`, format: `uuid` — Linked customer ID - **`id`** `string`, format: `uuid` — Borrower ID - **`mortgage_file_id`** `string`, format: `uuid` - **`order_index`** `integer` - **`organization_id`** `string`, format: `uuid` - **`preferred_contact_methods`** `array | null` **Items:** `string` - **`relationship_type`** `string | null`, possible values: `"main", "spouse", "business_partner", "siblings", "other"` - **`spouse_of_borrower_id`** `string | null`, format: `uuid` - **`updated_at`** `string | null`, format: `date-time` - **`child_errors`** `array` — Present only when saving a related entity failed (the file itself was saved). Each item has the form \`\: \\`, for example \`borrower\[1]: invalid_customer_id\`, \`borrower\[0]: 23502\` or \`incomes: 23514\`. **Items:** `string` - **`incomes`** `object | null` — The saved income data (Incomes structure), or null if it was not sent or saving failed - **`obligations`** `array | null` — The saved obligations, or null **Items:** *Schema `Obligation` is shown above.* schema: `MortgageFileCreateResult` — File creation response: the file record together with the results of creating the borrowers, incomes, bank accounts, and obligations **Example: default** ```json { "id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "organization_id": "0b8e1f2a-7c3d-4a5b-9e6f-2a3b4c5d6e7f", "file_number": "2026-0042", "title": "Apartment purchase - Cohen family", "status": "setup", "customer_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "assigned_to": null, "purposes": [ { "type": "second_hand", "amount": 1200000 } ], "loan_amount": 1200000, "property_type": "apartment", "property_value": 2000000, "property_address": "10 Herzl St., Ramat Gan", "equity": 800000, "created_at": "2026-10-14T08:15:22.481234+00:00", "updated_at": "2026-10-14T08:15:22.481234+00:00", "borrowers": [ { "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "organization_id": "0b8e1f2a-7c3d-4a5b-9e6f-2a3b4c5d6e7f", "mortgage_file_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "customer_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "order_index": 0, "relationship_type": "main", "borrower_type": "regular", "custom_relationship": null, "preferred_contact_methods": [] }, { "id": "3c4d5e6f-7a8b-4c9d-8e0f-2a3b4c5d6e7f", "organization_id": "0b8e1f2a-7c3d-4a5b-9e6f-2a3b4c5d6e7f", "mortgage_file_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "customer_id": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f", "order_index": 1, "relationship_type": "spouse", "borrower_type": "regular", "custom_relationship": null, "preferred_contact_methods": [] } ], "incomes": { "borrowers": [ { "borrowerName": "Yossi Cohen", "employments": [ { "type": "salaried", "data": { "employers": [ { "company_name": "Example Company Ltd.", "position": "Engineer", "start_date": "2019-01-01", "is_current": true } ] } } ] } ] }, "bank_accounts": [ { "bankName": "12", "bankDisplayName": "Example Bank", "branchName": "600", "branchDisplayName": "Central Branch", "accountNumber": "123456", "isJoint": true } ], "obligations": [ { "type": "bank_loan", "monthlyPayment": 1500, "remainingAmount": 30000, "endDate": "2027-12-31" } ] } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a mortgage file - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}` - **Operation ID:** `getMortgageFileById` - **Tags:** Mortgage files Returns the mortgage file together with a borrowers array containing the file's active borrowers. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Responses ##### Status: 200 Mortgage file details ###### Content-Type: application/json *Schema `MortgageFileDetails` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "", "borrowers": [ { "id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "spouse_of_borrower_id": "", "customer_id": "", "order_index": 1, "mortgage_file_id": "", "organization_id": "", "created_at": "", "updated_at": "" } ] } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a mortgage file - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}` - **Operation ID:** `updateMortgageFile` - **Tags:** Mortgage files Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. You can also update incomes, bank_accounts, and obligations. The value you send replaces the stored value (sending only bank_accounts leaves the stored obligations unchanged, and vice versa). Borrowers are not updated here; use /mortgage-files/{id}/borrowers instead. To change the status, we recommend using PATCH /mortgage-files/{id}/status. The response does not include borrowers. incomes, bank_accounts, and obligations are returned only if they were sent in the request (otherwise null). Failures to save them are reported in child_errors. customer_id, lead_id and source_lead_id must be IDs of active records in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateMortgageFile` — Partial update of a file: only the fields sent are updated. Borrowers cannot be updated through this endpoint. Fields not listed here are ignored. - **`additional_expenses`** `array` — Ancillary expenses **Items:** *Schema `AdditionalExpense` is shown above.* - **`additional_info`** `object` — Extended additional information **All of:** *Schema `MortgageAdditionalInfo` is shown above.* - **`appraiser_value`** `number` — Property value as assessed by the appraiser - **`assigned_to`** `string | null`, format: `uuid` — ID of a user in the organization. null or an empty string removes the assignment; an ID that does not belong to an active user in the organization is ignored - **`bank_accounts`** `array` — Bank accounts. Replaces the stored value; the stored obligations are unchanged if not sent **Items:** *Schema `BankAccount` is shown above.* - **`contract_date_payment`** `string` — Payment date under the contract - **`custom_fields_mortgage`** `object` — Custom fields **Additional properties:** any (true schema) - **`customer_id`** `string`, format: `uuid` — ID of the file's primary customer - **`eligibility`** `number` — Eligibility amount - **`equity`** `number` — Equity - **`file_number`** `string` — File number - **`financing_entity`** `object` — Financing entity details (bank) **All of:** *Schema `FinancingEntity` is shown above.* - **`incomes`** `object` — Income data. Replaces the stored value **All of:** *Schema `Incomes` is shown above.* - **`interest_rate`** `number` — Average interest rate - **`lead_id`** `string`, format: `uuid` — Linked lead ID - **`lead_source`** `string` — Lead source - **`loan_amount`** `number` — Requested mortgage amount - **`loan_purpose`** `string` — Loan purpose - **`loan_term`** `integer` — Loan term in months - **`monthly_payment`** `number` — Expected monthly payment - **`notes`** `string` — General notes - **`obligations`** `array` — Obligations. Replaces the stored value; the stored bank_accounts are unchanged if not sent **Items:** *Schema `Obligation` is shown above.* - **`property_address`** `string` — Full property address - **`property_type`** `string` — Property type (apartment, private house, plot, etc.) - **`property_value`** `number` — Property value - **`purposes`** `array` — Mortgage purposes (replaces the stored array) **Items:** *Schema `MortgagePurpose` is shown above.* - **`real_estate_details`** `object` — Extended real estate details **Additional properties:** any (true schema) - **`remaining_mortgage`** `number` — Remaining balance of the existing mortgage (for refinancing) - **`source_lead_id`** `string`, format: `uuid` — ID of the original lead the file was created from - **`source_lead_number`** `string` — Number of the original lead - **`status`** `string` — A valid status key in the organization. To change the status, using PATCH /mortgage-files/{id}/status is recommended - **`status_comment`** `string` — Comment on the current status - **`tax_declaration`** `string` — Real estate tax (Mas Shevach) declaration: single apartment, replacement apartment or investment apartment. Values: \`GET /api-service/lists/mishach-types\` - **`title`** `string` — File title or name - **`total_amount`** `number` — Total transaction amount **Example:** ```json { "file_number": "", "title": "", "status": "", "status_comment": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "lead_id": "", "source_lead_id": "", "source_lead_number": "", "incomes": { "borrowers": [ { "borrowerId": "", "borrowerName": "", "employments": [ { "type": "salaried", "data": { "employers": [ { "company_name": "", "position": "", "start_date": "", "is_current": true, "end_date": "", "salary_slips": [ {} ] } ], "is_public_sector": true, "is_controlling_employee": true, "business_name": "", "business_type": "", "years_active": 1, "average_monthly_income": "", "monthly_amount": "", "source": "", "scholarship_amount": "", "institution": "", "description": "", "amount": "" } } ] } ] }, "bank_accounts": [ { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "", "borrowers": [ "" ], "isJoint": true } ], "obligations": [ { "id": "", "type": "bank_loan", "customType": "", "monthlyPayment": 1, "remainingAmount": 1, "endDate": "", "bank_id": "", "bankData": { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "" }, "assignedBorrowers": [ "" ] } ] } ``` #### Responses ##### Status: 200 The updated mortgage file ###### Content-Type: application/json **All of:** *Schema `MortgageFile` is shown above.* - **`bank_accounts`** `array | null` — The stored bank accounts, or null if neither bank_accounts nor obligations was sent in the request **Items:** *Schema `BankAccount` is shown above.* - **`child_errors`** `array` — Present only when saving a related entity failed (the file itself was saved). Each item has the form \`\: \\`, for example \`borrower\[1]: invalid_customer_id\`, \`borrower\[0]: 23502\` or \`incomes: 23514\`. **Items:** `string` - **`incomes`** `object | null` — The saved income data, or null if incomes was not sent in the request - **`obligations`** `array | null` — The stored obligations, or null if neither bank_accounts nor obligations was sent in the request **Items:** *Schema `Obligation` is shown above.* schema: `MortgageFileUpdateResult` — File update response: the updated file record (without borrowers) together with the results of saving the incomes, bank accounts, and obligations **Example:** ```json { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "", "incomes": null, "bank_accounts": [ { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "", "borrowers": [ "" ], "isJoint": true } ], "obligations": [ { "id": "", "type": "bank_loan", "customType": "", "monthlyPayment": 1, "remainingAmount": 1, "endDate": "", "bank_id": "", "bankData": { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "" }, "assignedBorrowers": [ "" ] } ], "child_errors": [ "" ] } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a mortgage file - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}` - **Operation ID:** `patchMortgageFile` - **Tags:** Mortgage files Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. You can also update incomes, bank_accounts, and obligations. The value you send replaces the stored value (sending only bank_accounts leaves the stored obligations unchanged, and vice versa). Borrowers are not updated here; use /mortgage-files/{id}/borrowers instead. To change the status, we recommend using PATCH /mortgage-files/{id}/status. The response does not include borrowers. incomes, bank_accounts, and obligations are returned only if they were sent in the request (otherwise null). Failures to save them are reported in child_errors. customer_id, lead_id and source_lead_id must be IDs of active records in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateMortgageFile` is shown above.* **Example:** ```json { "file_number": "", "title": "", "status": "", "status_comment": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "lead_id": "", "source_lead_id": "", "source_lead_number": "", "incomes": { "borrowers": [ { "borrowerId": "", "borrowerName": "", "employments": [ { "type": "salaried", "data": { "employers": [ { "company_name": "", "position": "", "start_date": "", "is_current": true, "end_date": "", "salary_slips": [ {} ] } ], "is_public_sector": true, "is_controlling_employee": true, "business_name": "", "business_type": "", "years_active": 1, "average_monthly_income": "", "monthly_amount": "", "source": "", "scholarship_amount": "", "institution": "", "description": "", "amount": "" } } ] } ] }, "bank_accounts": [ { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "", "borrowers": [ "" ], "isJoint": true } ], "obligations": [ { "id": "", "type": "bank_loan", "customType": "", "monthlyPayment": 1, "remainingAmount": 1, "endDate": "", "bank_id": "", "bankData": { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "" }, "assignedBorrowers": [ "" ] } ] } ``` #### Responses ##### Status: 200 The updated mortgage file ###### Content-Type: application/json *Schema `MortgageFileUpdateResult` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "", "incomes": null, "bank_accounts": [ { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "", "borrowers": [ "" ], "isJoint": true } ], "obligations": [ { "id": "", "type": "bank_loan", "customType": "", "monthlyPayment": 1, "remainingAmount": 1, "endDate": "", "bank_id": "", "bankData": { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "" }, "assignedBorrowers": [ "" ] } ], "child_errors": [ "" ] } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Delete a mortgage file - **Method:** `DELETE` - **Path:** `/api-service/mortgage-files/{id}` - **Operation ID:** `deleteMortgageFile` - **Tags:** Mortgage files Soft delete: the mortgage file is marked as deleted and is no longer returned by the API. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Responses ##### Status: 200 Mortgage file deleted ###### Content-Type: application/json *Schema `DeleteResult` is shown above.* **Example: default** ```json { "success": true, "message": "Mortgage file deleted successfully" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a mortgage file's status - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/status` - **Operation ID:** `updateMortgageFileStatus` - **Tags:** Mortgage files Changes the mortgage file's status and updates status_changed_at. The status must be valid in the organization: a system status or a custom status (see GET /mortgage-files/statuses); otherwise the API returns 400 (code 23514). A missing status returns 400. notes (optional) is saved as the file's status_comment. The change is recorded in the file's timeline (event type status_updated). The response is the mortgage file record, without borrowers. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body The new status **Required:** `true` ##### Content-Type: application/json schema: `UpdateMortgageStatus` - **`status` (required)** `string` — Key of the new status: a system status or one of the organization's custom statuses (see GET /mortgage-files/statuses) - **`notes`** `string` — Comment on the status change (optional). Saved as the file's status_comment **Example: default** ```json { "status": "signing", "notes": "Approval in principle received" } ``` #### Responses ##### Status: 200 The mortgage file after the status update ###### Content-Type: application/json *Schema `MortgageFile` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List mortgage file statuses - **Method:** `GET` - **Path:** `/api-service/mortgage-files/statuses` - **Operation ID:** `getMortgageFileStatuses` - **Tags:** Mortgage files Returns the organization's mortgage file status configuration. If the organization has its own status configuration, source=custom and the items are the organization's definitions, excluding hidden statuses (items may include additional fields, such as each status's milestones). Otherwise, source=default and a fixed default list is returned. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Mortgage file statuses ###### Content-Type: application/json - **`count`** `integer` — Number of items in the data array - **`data`** `array` — List of statuses **Items:** schema: `MortgageStatus` — A mortgage file status, including the organization's custom statuses - **`bgColor`** `string` — Background color (HEX) - **`is_hidden`** `boolean` — Whether the status is hidden - **`is_system`** `boolean` — Whether this is a system status (cannot be deleted) - **`key`** `string` — Status identifier - **`label`** `string` — Display name in Hebrew - **`order`** `integer` — Display order - **`textColor`** `string` — Text color (HEX) - **`source`** `string`, possible values: `"default", "custom"` — Source of the list: the organization's configuration (custom) or the default list (default) **Example:** ```json { "data": [ { "key": "", "label": "", "bgColor": "", "textColor": "", "is_system": true, "is_hidden": true, "order": 1 } ], "count": 1, "source": "default" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's borrowers - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/borrowers` - **Operation ID:** `getMortgageFileBorrowers` - **Tags:** Borrowers Returns the mortgage file's active borrowers in their order (order_index), without pagination. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Responses ##### Status: 200 List of borrowers ###### Content-Type: application/json - **`count`** `integer` — Number of items in the data array - **`data`** `array` **Items:** *Schema `Borrower` is shown above.* **Example:** ```json { "data": [ { "id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "spouse_of_borrower_id": "", "customer_id": "", "order_index": 1, "mortgage_file_id": "", "organization_id": "", "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Add a borrower to a mortgage file - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/borrowers` - **Operation ID:** `addBorrowerToMortgageFile` - **Tags:** Borrowers Adds a borrower to the mortgage file and links it to a customer record: - If **id_number** is sent, the API looks up an active customer in the organization with the same ID number, and the customer fields you send **update the existing customer**. If no such customer exists, a new customer is created (id_type defaults to israeli_id; creating a customer requires first_name and last_name, otherwise the API returns 500 with code 23502). - If id_number is not sent, the borrower is linked to the customer_id you send (if any), **and the customer fields in the request are not saved**. customer_id must belong to an active customer in the organization; otherwise the API returns 400 (Invalid customer_id). Defaults: order_index = the number of existing borrowers in the mortgage file; relationship_type = main for the first borrower and spouse for subsequent ones; borrower_type = regular. A borrower with order_index=0 must be main (otherwise 400, code 23514). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body Borrower details **Required:** `true` ##### Content-Type: application/json *Schema `CreateBorrower` is shown above.* **Example: default** ```json { "first_name": "Ronit", "last_name": "Cohen", "id_number": "000000026", "phone": "054-0000000", "email": "ronit.cohen@example.com", "relationship_type": "spouse" } ``` #### Responses ##### Status: 201 Borrower added (including the linked customer's details) ###### Content-Type: application/json *Schema `Borrower` is shown above.* **Example:** ```json { "id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "spouse_of_borrower_id": "", "customer_id": "", "order_index": 1, "mortgage_file_id": "", "organization_id": "", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a borrower - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/borrowers/{borrowerId}` - **Operation ID:** `updateMortgageFileBorrower` - **Tags:** Borrowers Partial update (PUT and PATCH behave identically). Customer fields (name, identification, contact details, etc.) update the linked customer record, and the change applies to every mortgage file in which that customer is a borrower; for a borrower that is not linked to a customer, these fields are not saved. Association fields (relationship_type, custom_relationship, borrower_type, preferred_contact_methods, order_index) apply only to the borrower in this mortgage file. A request with no recognized fields returns the borrower unchanged. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `borrowerId` required - **In:** `path` Borrower ID (the id from the mortgage file's list of borrowers) `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateBorrower` — Partial update of a borrower. Customer fields update the linked customer record (and apply to all of that customer's files); link fields (relationship_type, custom_relationship, borrower_type, preferred_contact_methods, order_index) apply only to the borrower in this file. - **`birth_date`** `string`, format: `date` — Date of birth - **`borrower_type`** `string`, possible values: `"regular", "paying_guarantor", "supporting_guarantor", "non_mortgaging_borrower"` — Borrower type - **`children_birth_dates`** `array` — Children's dates of birth **Items:** `string`, format: `date` - **`children_under_18`** `integer` — Number of children under 18 - **`city`** `string` — City of residence - **`custom_marital_status`** `string` — Custom marital status (when marital_status=other) - **`custom_relationship`** `string` — Custom relationship type (when relationship_type=other) - **`email`** `string`, format: `email` — Email address - **`entity_name`** `string` — Name of the company or nonprofit association (when id_type is company or association) - **`first_name`** `string` — First name - **`foreign_citizenship`** `string` — Country of the foreign citizenship - **`gender`** `string`, possible values: `"male", "female", "other"` — Gender - **`has_children`** `boolean` — Whether the borrower has children - **`has_foreign_citizenship`** `boolean` — Whether the borrower holds foreign citizenship - **`id_country`** `string` — Country that issued the identification document (relevant for passports) - **`id_expiry_date`** `string`, format: `date` — Expiry date of the identification document - **`id_number`** `string` — Identification document number of the linked customer - **`id_type`** `string`, possible values: `"israeli_id", "passport", "association", "company"` — Identification document type - **`is_politically_exposed`** `boolean` — Whether the borrower is a politically exposed person (PEP) - **`issue_date`** `string`, format: `date` — Issue date of the identification document - **`last_name`** `string` — Last name - **`marital_status`** `string`, possible values: `"single", "married", "divorced", "widowed", "separated", "domestic_partnership", "other"` — Marital status - **`order_index`** `integer` — The borrower's position in the file (0 = primary borrower) - **`phone`** `string` — Phone number - **`preferred_contact_methods`** `array` — Preferred contact methods **Items:** `string`, possible values: `"email", "sms", "whatsapp", "voice", "no_sms"` - **`relationship_type`** `string`, possible values: `"main", "spouse", "business_partner", "siblings", "other"` — The borrower's relationship to the file. The borrower with order_index=0 must be main - **`street`** `string` — Street of residence **Example:** ```json { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "preferred_contact_methods": [ "email" ], "order_index": 1 } ``` #### Responses ##### Status: 200 The updated borrower ###### Content-Type: application/json *Schema `Borrower` is shown above.* **Example:** ```json { "id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "spouse_of_borrower_id": "", "customer_id": "", "order_index": 1, "mortgage_file_id": "", "organization_id": "", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a borrower - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/borrowers/{borrowerId}` - **Operation ID:** `patchMortgageFileBorrower` - **Tags:** Borrowers Partial update (PUT and PATCH behave identically). Customer fields (name, identification, contact details, etc.) update the linked customer record, and the change applies to every mortgage file in which that customer is a borrower; for a borrower that is not linked to a customer, these fields are not saved. Association fields (relationship_type, custom_relationship, borrower_type, preferred_contact_methods, order_index) apply only to the borrower in this mortgage file. A request with no recognized fields returns the borrower unchanged. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `borrowerId` required - **In:** `path` Borrower ID (the id from the mortgage file's list of borrowers) `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateBorrower` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "preferred_contact_methods": [ "email" ], "order_index": 1 } ``` #### Responses ##### Status: 200 The updated borrower ###### Content-Type: application/json *Schema `Borrower` is shown above.* **Example:** ```json { "id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "spouse_of_borrower_id": "", "customer_id": "", "order_index": 1, "mortgage_file_id": "", "organization_id": "", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Remove a borrower from a mortgage file - **Method:** `DELETE` - **Path:** `/api-service/mortgage-files/{id}/borrowers/{borrowerId}` - **Operation ID:** `removeBorrowerFromMortgageFile` - **Tags:** Borrowers Removes the borrower from the mortgage file (a soft delete of the association). The customer record itself is not deleted. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `borrowerId` required - **In:** `path` Borrower ID (the id from the mortgage file's list of borrowers) `string`, format: `uuid` #### Responses ##### Status: 200 Borrower removed ###### Content-Type: application/json *Schema `DeleteResult` is shown above.* **Example: default** ```json { "success": true, "message": "Borrower deleted successfully" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List customers - **Method:** `GET` - **Path:** `/api-service/customers` - **Operation ID:** `getCustomers` - **Tags:** Customers Returns the organization's customers (excluding deleted customers), newest first, with pagination. The list does not include mortgage_files; they are returned only when you retrieve a single customer. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` ##### `search` - **In:** `query` Partial, case-insensitive search across first name, last name, phone, email, and ID number. The characters , ( ) % \_ \ " ' are removed from the search term before searching. `string` #### Responses ##### Status: 200 List of customers ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `Customer` — A customer in the organization. The response may include additional columns that are not documented here. - **`first_name` (required)** `string` — First name - **`last_name` (required)** `string` — Last name - **`birth_date`** `string`, format: `date` — Date of birth - **`children_birth_dates`** `array` — Children's dates of birth **Items:** `string`, format: `date` - **`children_under_18`** `integer` — Number of children under 18 - **`city`** `string` — City - **`created_at`** `string`, format: `date-time` — Creation date - **`custom_marital_status`** `string` — Custom marital status (when marital_status=other) - **`email`** `string`, format: `email` — Email address - **`entity_name`** `string` — Name of the company or nonprofit association (when id_type is company or association) - **`foreign_citizenship`** `string` — Country of foreign citizenship - **`gender`** `string`, possible values: `"male", "female", "other"` — Gender - **`has_children`** `boolean` — Whether the customer has children - **`has_foreign_citizenship`** `boolean` — Whether the customer holds foreign citizenship - **`id`** `string`, format: `uuid` — Customer ID - **`id_country`** `string` — Country that issued the identification document (relevant for passports) - **`id_expiry_date`** `string`, format: `date` — Expiration date of the identification document - **`id_number`** `string` — Identification document number - **`id_type`** `string`, possible values: `"israeli_id", "passport", "association", "company"` — Identification document type - **`is_politically_exposed`** `boolean` — Whether the customer is a politically exposed person (PEP) - **`issue_date`** `string`, format: `date` — Issue date of the identification document - **`marital_status`** `string`, possible values: `"single", "married", "divorced", "widowed", "separated", "domestic_partnership", "other"` — Marital status - **`mortgage_files`** `array` — Returned only by GET /customers/{id}: the active mortgage files in which this customer is the primary customer (customer_id), without borrowers **Items:** *Schema `MortgageFile` is shown above.* - **`organization_id`** `string`, format: `uuid` — Organization ID - **`phone`** `string` — Phone number - **`street`** `string` — Street - **`updated_at`** `string`, format: `date-time` — Last updated date **Example:** ```json { "data": [ { "id": "", "organization_id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "created_at": "", "updated_at": "", "mortgage_files": [ { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "" } ] } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a customer - **Method:** `POST` - **Path:** `/api-service/customers` - **Operation ID:** `createCustomer` - **Tags:** Customers Creates a new customer in the organization. - Required: first_name and last_name. A missing field returns 400 with a validation object. - id_type defaults to israeli_id. - If id_number already belongs to an active customer in the organization, the API returns 409, and the existing customer's ID is returned in existing_customer_id. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Request Body Details of the new customer **Required:** `true` ##### Content-Type: application/json schema: `CreateCustomer` — Data for creating a customer. Fields not listed here are ignored. - **`first_name` (required)** `string` — First name - **`last_name` (required)** `string` — Last name - **`birth_date`** `string`, format: `date` — Date of birth - **`children_birth_dates`** `array` — Children's dates of birth **Items:** `string`, format: `date` - **`children_under_18`** `integer` — Number of children under 18 - **`city`** `string` — City - **`custom_marital_status`** `string` — Custom marital status (when marital_status=other) - **`email`** `string`, format: `email` — Email address - **`entity_name`** `string` — Name of the company or nonprofit association (when id_type is company or association) - **`foreign_citizenship`** `string` — Country of foreign citizenship - **`gender`** `string`, possible values: `"male", "female", "other"` — Gender - **`has_children`** `boolean` — Whether the customer has children - **`has_foreign_citizenship`** `boolean` — Whether the customer holds foreign citizenship - **`id_country`** `string` — Country that issued the identification document (relevant for passports) - **`id_expiry_date`** `string`, format: `date` — Expiration date of the identification document - **`id_number`** `string` — Identification document number. Unique within the organization - if a customer with the same number already exists, 409 is returned - **`id_type`** `string`, possible values: `"israeli_id", "passport", "association", "company"`, default: `"israeli_id"` — Identification document type - **`is_politically_exposed`** `boolean` — Whether the customer is a politically exposed person (PEP) - **`issue_date`** `string`, format: `date` — Issue date of the identification document - **`marital_status`** `string`, possible values: `"single", "married", "divorced", "widowed", "separated", "domestic_partnership", "other"` — Marital status - **`phone`** `string` — Phone number - **`street`** `string` — Street **Example: default** ```json { "first_name": "Yossi", "last_name": "Cohen", "id_type": "israeli_id", "id_number": "000000018", "phone": "052-0000000", "email": "yossi.cohen@example.com", "birth_date": "1988-04-12", "gender": "male", "marital_status": "married", "street": "10 Herzl St.", "city": "Ramat Gan" } ``` #### Responses ##### Status: 201 Customer created ###### Content-Type: application/json *Schema `Customer` is shown above.* **Example: default** ```json { "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "organization_id": "0b8e1f2a-7c3d-4a5b-9e6f-2a3b4c5d6e7f", "first_name": "Yossi", "last_name": "Cohen", "id_type": "israeli_id", "id_number": "000000018", "phone": "052-0000000", "email": "yossi.cohen@example.com", "birth_date": "1988-04-12", "gender": "male", "marital_status": "married", "street": "10 Herzl St.", "city": "Ramat Gan", "created_at": "2026-10-14T08:15:22.481234+00:00", "updated_at": "2026-10-14T08:15:22.481234+00:00" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 409 A customer with the same id_number already exists in the organization. The existing customer's ID is returned in existing_customer_id ###### Content-Type: application/json schema: `ErrorResponse` — A consistent structure for all error responses. In addition to the fixed error and status fields, some errors add context fields - for example validation, existing_customer_id, related_files_count, related_mortgages_count, existing_link_id, existing_id, provided_type, or available_lists. - **`error` (required)** `string` — Short description of the error (in English) - **`status` (required)** `integer` — HTTP status code (same as the response code) - **`code`** `string` — The PostgREST/Postgres error code, when it is safe to expose: on 400 (22P02, 23503, 23514), 409 (23505) and 500 - **`details`** `string` — Additional details, when available. Never includes raw database messages - **`reason`** `string`, possible values: `"missing_api_key", "malformed_api_key", "invalid_api_key", "auth_service_error"` — 401 only: the reason the key was rejected - **`retry_after`** `string`, format: `date-time` — 429 only: when the rate-limit window resets - **`validation`** `object` — On 400 for missing required fields: a map from each field name to the message "Required field" **Additional properties:** `string` **Additional properties:** any (true schema) **Example: default** ```json { "error": "Customer with this ID number already exists", "details": "A customer with this ID number is already registered in your organization", "status": 409, "existing_customer_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d" } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a customer - **Method:** `GET` - **Path:** `/api-service/customers/{id}` - **Operation ID:** `getCustomerById` - **Tags:** Customers Returns the customer together with mortgage_files: the active mortgage files in which the customer is the primary customer (customer_id), without borrowers. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Customer ID `string`, format: `uuid` #### Responses ##### Status: 200 Customer details ###### Content-Type: application/json *Schema `Customer` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "created_at": "", "updated_at": "", "mortgage_files": [ { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "" } ] } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a customer - **Method:** `PUT` - **Path:** `/api-service/customers/{id}` - **Operation ID:** `updateCustomer` - **Tags:** Customers Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. Updates do not check id_number for duplicates at the API level; a number that already belongs to another customer is rejected by the database (409, code 23505). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Customer ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateCustomer` — Partial update of a customer: only the fields sent are updated. Fields not listed here are ignored. - **`birth_date`** `string`, format: `date` — Date of birth - **`children_birth_dates`** `array` — Children's dates of birth **Items:** `string`, format: `date` - **`children_under_18`** `integer` — Number of children under 18 - **`city`** `string` — City - **`custom_marital_status`** `string` — Custom marital status (when marital_status=other) - **`email`** `string`, format: `email` — Email address - **`entity_name`** `string` — Name of the company or nonprofit association (when id_type is company or association) - **`first_name`** `string` — First name - **`foreign_citizenship`** `string` — Country of the foreign citizenship - **`gender`** `string`, possible values: `"male", "female", "other"` — Gender - **`has_children`** `boolean` — Whether the customer has children - **`has_foreign_citizenship`** `boolean` — Whether the customer holds foreign citizenship - **`id_country`** `string` — Country that issued the identification document (relevant for passports) - **`id_expiry_date`** `string`, format: `date` — Expiry date of the identification document - **`id_number`** `string` — Identification document number. Unique within the organization: a number that already belongs to another customer is rejected by the database (409, code 23505) - **`id_type`** `string`, possible values: `"israeli_id", "passport", "association", "company"` — Identification document type - **`is_politically_exposed`** `boolean` — Whether the customer is a politically exposed person (PEP) - **`issue_date`** `string`, format: `date` — Issue date of the identification document - **`last_name`** `string` — Last name - **`marital_status`** `string`, possible values: `"single", "married", "divorced", "widowed", "separated", "domestic_partnership", "other"` — Marital status - **`phone`** `string` — Phone number - **`street`** `string` — Street **Example:** ```json { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true } ``` #### Responses ##### Status: 200 The updated customer ###### Content-Type: application/json *Schema `Customer` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "created_at": "", "updated_at": "", "mortgage_files": [ { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "" } ] } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a customer - **Method:** `PATCH` - **Path:** `/api-service/customers/{id}` - **Operation ID:** `partialUpdateCustomer` - **Tags:** Customers Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. Updates do not check id_number for duplicates at the API level; a number that already belongs to another customer is rejected by the database (409, code 23505). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Customer ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateCustomer` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true } ``` #### Responses ##### Status: 200 The updated customer ###### Content-Type: application/json *Schema `Customer` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "created_at": "", "updated_at": "", "mortgage_files": [ { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "" } ] } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Delete a customer - **Method:** `DELETE` - **Path:** `/api-service/customers/{id}` - **Operation ID:** `deleteCustomer` - **Tags:** Customers Soft delete. A customer who is the primary customer of an active mortgage file cannot be deleted; the API returns 409 with related_files_count. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Customer ID `string`, format: `uuid` #### Responses ##### Status: 200 Customer deleted ###### Content-Type: application/json *Schema `DeleteResult` is shown above.* **Example: default** ```json { "success": true, "message": "Customer deleted successfully" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 The customer has active mortgage files. Their count is returned in related_files_count ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Cannot delete customer", "details": "This customer has active mortgage files. You must delete the mortgage files first.", "status": 409, "related_files_count": 2 } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a customer's mortgage files - **Method:** `GET` - **Path:** `/api-service/customers/{id}/mortgage-files` - **Operation ID:** `getCustomerMortgageFiles` - **Tags:** Customers, Mortgage files Returns the active mortgage files in which the customer is the primary customer (customer_id), newest first. To filter and paginate, use GET /mortgage-files?customer_id={id}. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Customer ID `string`, format: `uuid` #### Responses ##### Status: 200 The customer's mortgage files ###### Content-Type: application/json - **`count`** `integer` — Number of mortgage files - **`data`** `array` **Items:** *Schema `MortgageFile` is shown above.* **Example:** ```json { "data": [ { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List available lists - **Method:** `GET` - **Path:** `/api-service/lists` - **Operation ID:** `getAvailableLists` - **Tags:** Lists Returns all available lists, with the path and number of items of each. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Available lists ###### Content-Type: application/json - **`count`** `integer` — Number of available lists - **`data`** `array` **Items:** - **`count`** `integer` — Number of items in the list - **`endpoint`** `string` — API path for retrieving the list - **`key`** `string` — List identifier - **`description`** `string` **Example: default** ```json { "data": [ { "key": "employment-types", "endpoint": "/api-service/lists/employment-types", "count": 9 }, { "key": "income-types", "endpoint": "/api-service/lists/income-types", "count": 5 }, { "key": "obligation-types", "endpoint": "/api-service/lists/obligation-types", "count": 6 }, { "key": "mortgage-types", "endpoint": "/api-service/lists/mortgage-types", "count": 20 }, { "key": "registration-types", "endpoint": "/api-service/lists/registration-types", "count": 9 }, { "key": "mishach-types", "endpoint": "/api-service/lists/mishach-types", "count": 3 }, { "key": "upload-document-statuses", "endpoint": "/api-service/lists/upload-document-statuses", "count": 6 }, { "key": "signature-document-statuses", "endpoint": "/api-service/lists/signature-document-statuses", "count": 4 }, { "key": "additional-expense-types", "endpoint": "/api-service/lists/additional-expense-types", "count": 8 }, { "key": "calendar-event-types", "endpoint": "/api-service/lists/calendar-event-types", "count": 10 } ], "count": 10, "description": "רשימת כל סוגי הרשימות הזמינות" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List employment types - **Method:** `GET` - **Path:** `/api-service/lists/employment-types` - **Operation ID:** `getEmploymentTypes` - **Tags:** Lists Returns the employment types (salaried employee, self-employed, retiree, etc.). These are the keys for the employment type field in the incomes structure. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Employment types ###### Content-Type: application/json schema: `ListResponse` — Basic list response - **`count`** `integer` — Number of items - **`data`** `array` — List items **Items:** schema: `ListItem` — An item in a basic list - **`key` (required)** `string` — Item identifier - **`label` (required)** `string` — Display name in Hebrew - **`list_type`** `string` — List type **Example: default** ```json { "data": [ { "key": "salaried", "label": "שכיר" }, { "key": "self_employed", "label": "עצמאי" }, { "key": "scholarship", "label": "מלגת לימודים" }, { "key": "child_benefit", "label": "קצבת ילדים" }, { "key": "kollel", "label": "אברך כולל" }, { "key": "pension", "label": "פנסיה" }, { "key": "allowance", "label": "קצבה" }, { "key": "other", "label": "אחר" }, { "key": "unemployed", "label": "לא עובד" } ], "count": 9, "list_type": "employment-types" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List additional income types - **Method:** `GET` - **Path:** `/api-service/lists/income-types` - **Operation ID:** `getIncomeTypes` - **Tags:** Lists Returns the additional income types (rental, dividends, alimony, etc.). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Additional income types ###### Content-Type: application/json *Schema `ListResponse` is shown above.* **Example: default** ```json { "data": [ { "key": "rental", "label": "הכנסה מדירה/נכס" }, { "key": "dividend", "label": "דיבידנד" }, { "key": "alimony", "label": "מזונות" }, { "key": "child_disability", "label": "קצבת ילד נכה" }, { "key": "other", "label": "אחר" } ], "count": 5, "list_type": "income-types" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List obligation types - **Method:** `GET` - **Path:** `/api-service/lists/obligation-types` - **Operation ID:** `getObligationTypes` - **Tags:** Lists Returns the obligation types (loans, mortgage, alimony, etc.). These are the keys for the type field in obligations. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Obligation types ###### Content-Type: application/json *Schema `ListResponse` is shown above.* **Example: default** ```json { "data": [ { "key": "bank_loan", "label": "הלוואה בנקאית" }, { "key": "non_bank_loan", "label": "הלוואה חוץ בנקאית" }, { "key": "mortgage", "label": "משכנתא" }, { "key": "alimony", "label": "מזונות" }, { "key": "rent", "label": "שכירות" }, { "key": "other", "label": "אחר" } ], "count": 6, "list_type": "obligation-types" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List mortgage types - **Method:** `GET` - **Path:** `/api-service/lists/mortgage-types` - **Operation ID:** `getMortgageTypes` - **Tags:** Lists Returns the mortgage types (purchase from a contractor, second-hand purchase, refinancing, etc.). These are the keys for the purposes\[].type field of a mortgage file. The list also includes legacy combined types retained for backward compatibility. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Mortgage types ###### Content-Type: application/json *Schema `ListResponse` is shown above.* **Example: default** ```json { "data": [ { "key": "new_contractor", "label": "רכישה מקבלן" }, { "key": "subsidized_price", "label": "רכישה במחיר למשתכן" }, { "key": "second_hand", "label": "רכישה יד שניה" }, { "key": "amidar", "label": "רכישה מעמידר" }, { "key": "divorce", "label": "רכישה אגב גירושין" }, { "key": "land_purchase_rami", "label": "רכישת מגרש מרמ\"י" }, { "key": "refinance", "label": "מיחזור משכנתא" }, { "key": "expansion", "label": "הרחבה / בניה עצמית" }, { "key": "first_expansion", "label": "הרחבה (משכנתא ראשונה)" }, { "key": "renovations", "label": "שיפוצים" }, { "key": "any_purpose", "label": "כל מטרה" }, { "key": "dowry", "label": "נדוניה" }, { "key": "bridge_loan", "label": "הלוואת גישור" }, { "key": "business_loan", "label": "הלוואה עסקית" }, { "key": "overdraft_loan", "label": "הלוואת עו\"ש" }, { "key": "self_construction", "label": "בניה עצמית" }, { "key": "refinance_expansion", "label": "מיחזור + הרחבה" }, { "key": "refinance_renovations", "label": "מיחזור + שיפוצים" }, { "key": "refinance_any_purpose", "label": "מיחזור + כל מטרה" }, { "key": "refinance_dowry", "label": "מיחזור + נדוניה" } ], "count": 20, "list_type": "mortgage-types" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List property registration types - **Method:** `GET` - **Path:** `/api-service/lists/registration-types` - **Operation ID:** `getRegistrationTypes` - **Tags:** Lists Returns the property registration types (Land Registry (Tabu), Israel Land Authority (RMI), housing company, etc.). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Registration types ###### Content-Type: application/json *Schema `ListResponse` is shown above.* **Example: default** ```json { "data": [ { "key": "tabu", "label": "טאבו" }, { "key": "tabu_mortgage_company", "label": "טאבו + חברה משכנת" }, { "key": "tabu_no_ownership", "label": "טאבו ללא בעלות" }, { "key": "tabu_musha", "label": "טאבו במושע" }, { "key": "rami", "label": "רמי" }, { "key": "rami_mortgage_company", "label": "רמי + חברה משכנת" }, { "key": "zionist_organization", "label": "ההסתדרות הציונית" }, { "key": "jordanian_tabu", "label": "טאבו ירדני" }, { "key": "other", "label": "אחר" } ], "count": 9, "list_type": "registration-types" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List real estate tax (Mas Shevach) declaration types - **Method:** `GET` - **Path:** `/api-service/lists/mishach-types` - **Operation ID:** `getMishachTypes` - **Tags:** Lists Returns the real estate tax (Mas Shevach) declaration types: single apartment, replacement apartment and investment apartment. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Real estate tax (Mas Shevach) declaration types ###### Content-Type: application/json *Schema `ListResponse` is shown above.* **Example: default** ```json { "data": [ { "key": "single_apartment", "label": "דירה יחידה" }, { "key": "replacement_apartment", "label": "דירה חליפית" }, { "key": "investment_apartment", "label": "דירה להשקעה" } ], "count": 3, "list_type": "mishach-types" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List document upload statuses - **Method:** `GET` - **Path:** `/api-service/lists/upload-document-statuses` - **Operation ID:** `getUploadDocumentStatuses` - **Tags:** Lists Returns the statuses of a document requested for upload, with display colors (HEX). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Document upload statuses ###### Content-Type: application/json schema: `StatusListResponse` — Status list response - **`count`** `integer` — Number of items - **`data`** `array` — List items **Items:** schema: `StatusListItem` — An item in a status list, with colors - **`bgColor` (required)** `string` — Background color (HEX) - **`key` (required)** `string` — Status identifier - **`label` (required)** `string` — Display name in Hebrew - **`textColor` (required)** `string` — Text color (HEX) - **`list_type`** `string` — List type **Example: default** ```json { "data": [ { "key": "pending", "label": "ממתין להעלאה", "bgColor": "#fef9c3", "textColor": "#854d0e" }, { "key": "uploading", "label": "בהעלאה", "bgColor": "#dbeafe", "textColor": "#1d4ed8" }, { "key": "under_review", "label": "בבדיקה", "bgColor": "#f3e8ff", "textColor": "#7e22ce" }, { "key": "completed", "label": "הושלם", "bgColor": "#dcfce7", "textColor": "#166534" }, { "key": "rejected", "label": "נדחה", "bgColor": "#fee2e2", "textColor": "#dc2626" }, { "key": "expired", "label": "פג תוקף", "bgColor": "#f3f4f6", "textColor": "#4b5563" } ], "count": 6, "list_type": "upload-document-statuses" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List document signature statuses - **Method:** `GET` - **Path:** `/api-service/lists/signature-document-statuses` - **Operation ID:** `getSignatureDocumentStatuses` - **Tags:** Lists Returns the statuses of a document sent for signature, with display colors (HEX). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Document signature statuses ###### Content-Type: application/json *Schema `StatusListResponse` is shown above.* **Example: default** ```json { "data": [ { "key": "pending", "label": "ממתין לחתימה", "bgColor": "#fef9c3", "textColor": "#854d0e" }, { "key": "under_review", "label": "בבדיקה", "bgColor": "#ffedd5", "textColor": "#c2410c" }, { "key": "completed", "label": "נחתם", "bgColor": "#dcfce7", "textColor": "#166534" }, { "key": "rejected", "label": "נדחה", "bgColor": "#fee2e2", "textColor": "#dc2626" } ], "count": 4, "list_type": "signature-document-statuses" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List additional expense types - **Method:** `GET` - **Path:** `/api-service/lists/additional-expense-types` - **Operation ID:** `getAdditionalExpenseTypes` - **Tags:** Lists Returns the types of additional transaction expenses (purchase tax, legal fees, brokerage, etc.). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Additional expense types ###### Content-Type: application/json *Schema `ListResponse` is shown above.* **Example: default** ```json { "data": [ { "key": "purchase_tax", "label": "מס רכישה" }, { "key": "lawyer_fee", "label": "שכר טרחה עו\"ד" }, { "key": "brokerage", "label": "תיווך" }, { "key": "mortgage_consulting", "label": "ייעוץ משכנתאות" }, { "key": "renovation_furniture", "label": "שיפוץ וריהוט" }, { "key": "index_addition", "label": "תוספת עבור מדד" }, { "key": "appraisal", "label": "שמאות" }, { "key": "other", "label": "אחר" } ], "count": 8, "list_type": "additional-expense-types" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List calendar event types - **Method:** `GET` - **Path:** `/api-service/lists/calendar-event-types` - **Operation ID:** `getCalendarEventTypes` - **Tags:** Lists Returns the calendar event types (task, reminder, meeting, etc.), with color, icon, and sort order. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Responses ##### Status: 200 Calendar event types ###### Content-Type: application/json schema: `CalendarEventTypeListResponse` — Calendar event type list response - **`count`** `integer` — Number of types - **`data`** `array` — Event types **Items:** schema: `CalendarEventTypeItem` — A calendar event type - **`code` (required)** `string` — Event type identifier - **`color` (required)** `string` — Event color (HEX) - **`name` (required)** `string` — Name in Hebrew - **`allowSync`** `boolean` — Whether syncing is allowed - **`icon`** `string` — Icon name - **`nameEn`** `string` — Name in English - **`showInCalendar`** `boolean` — Whether the event type is shown in the calendar - **`sortOrder`** `integer` — Sort order - **`list_type`** `string` — List type **Example: default** ```json { "data": [ { "code": "task", "name": "משימה", "nameEn": "Task", "color": "#3b82f6", "icon": "check-square", "sortOrder": 1, "showInCalendar": true, "allowSync": true }, { "code": "reminder", "name": "תזכורת", "nameEn": "Reminder", "color": "#f59e0b", "icon": "bell", "sortOrder": 2, "showInCalendar": true, "allowSync": true }, { "code": "payment", "name": "תשלום", "nameEn": "Payment", "color": "#10b981", "icon": "credit-card", "sortOrder": 3, "showInCalendar": true, "allowSync": true }, { "code": "meeting", "name": "פגישה", "nameEn": "Meeting", "color": "#8b5cf6", "icon": "users", "sortOrder": 4, "showInCalendar": true, "allowSync": true }, { "code": "deadline", "name": "דד-ליין", "nameEn": "Deadline", "color": "#ef4444", "icon": "alert-circle", "sortOrder": 5, "showInCalendar": true, "allowSync": true }, { "code": "milestone", "name": "אבן דרך", "nameEn": "Milestone", "color": "#06b6d4", "icon": "flag", "sortOrder": 6, "showInCalendar": true, "allowSync": true }, { "code": "call", "name": "שיחה", "nameEn": "Call", "color": "#6366f1", "icon": "phone", "sortOrder": 7, "showInCalendar": true, "allowSync": true }, { "code": "document", "name": "מסמך", "nameEn": "Document", "color": "#84cc16", "icon": "file-text", "sortOrder": 8, "showInCalendar": true, "allowSync": true }, { "code": "borrower_signatures", "name": "חתימות לווים", "nameEn": "Borrower Signatures", "color": "#0ea5e9", "icon": "pen-tool", "sortOrder": 55, "showInCalendar": true, "allowSync": true }, { "code": "custom", "name": "אחר", "nameEn": "Other", "color": "#6b7280", "icon": "calendar", "sortOrder": 99, "showInCalendar": true, "allowSync": true } ], "count": 10, "list_type": "calendar-event-types" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List contacts - **Method:** `GET` - **Path:** `/api-service/contacts` - **Operation ID:** `getContacts` - **Tags:** Contacts Returns the organization's contacts (bankers, appraisers, lawyers, etc.), excluding deleted contacts, newest first, with pagination. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` ##### `search` - **In:** `query` Partial, case-insensitive search across first name, last name, phone, email, and company. The characters , ( ) % \_ \ " ' are removed from the search term before searching. `string` ##### `type` - **In:** `query` Filter by contact type `string`, possible values: `"banker", "appraiser", "lawyer", "insurance", "contractor", "other"` #### Responses ##### Status: 200 List of contacts ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `Contact` — An organization contact (banker, lawyer, appraiser, etc.) - **`company`** `string` — Company or organization - **`created_at`** `string`, format: `date-time` - **`custom_type`** `string | null` — Custom type when type = other - **`email`** `string`, format: `email` - **`first_name`** `string` — First name - **`id`** `string`, format: `uuid` - **`job_title`** `string` — Job title - **`last_name`** `string` — Last name - **`notes`** `string` — Notes - **`organization_id`** `string`, format: `uuid` - **`phone`** `string` — Phone - **`type`** `string`, possible values: `"banker", "lawyer", "appraiser", "insurance", "contractor", "other"` — Contact type. When other, details can be given in custom_type - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": null, "notes": "", "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a contact - **Method:** `POST` - **Path:** `/api-service/contacts` - **Operation ID:** `createContact` - **Tags:** Contacts Creates a contact in the organization. - Required: first_name, last_name, and type. A missing field returns 400 with a validation object. - type must be one of: banker, appraiser, lawyer, insurance, contractor, other. Otherwise, the API returns 400, and the value you sent is returned in provided_type. When type=other, you can specify the type in custom_type. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Request Body Contact details **Required:** `true` ##### Content-Type: application/json schema: `CreateContact` — Data for creating a contact. first_name, last_name, and type are required. - **`first_name` (required)** `string` - **`last_name` (required)** `string` - **`type` (required)** `string`, possible values: `"banker", "lawyer", "appraiser", "insurance", "contractor", "other"` — Contact type. When other, details can be given in custom_type - **`company`** `string` - **`custom_type`** `string` - **`email`** `string`, format: `email` - **`job_title`** `string` - **`notes`** `string` - **`phone`** `string` **Example: default** ```json { "first_name": "Michal", "last_name": "Avraham", "type": "banker", "company": "Example Bank", "job_title": "Mortgage banker", "phone": "03-0000000", "email": "michal.avraham@example.com", "notes": "Handles the branch's mortgage files" } ``` #### Responses ##### Status: 201 Contact created ###### Content-Type: application/json *Schema `Contact` is shown above.* **Example: default** ```json { "id": "9e0f1a2b-3c4d-4e5f-a6b7-c8d9e0f1a2b3", "organization_id": "0b8e1f2a-7c3d-4a5b-9e6f-2a3b4c5d6e7f", "first_name": "Michal", "last_name": "Avraham", "type": "banker", "company": "Example Bank", "job_title": "Mortgage banker", "phone": "03-0000000", "email": "michal.avraham@example.com", "notes": "Handles the branch's mortgage files", "custom_type": null, "created_at": "2026-10-14T08:15:22.481234+00:00", "updated_at": "2026-10-14T08:15:22.481234+00:00" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a contact - **Method:** `GET` - **Path:** `/api-service/contacts/{id}` - **Operation ID:** `getContactById` - **Tags:** Contacts Returns a contact by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Contact ID `string`, format: `uuid` #### Responses ##### Status: 200 Contact details ###### Content-Type: application/json *Schema `Contact` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": null, "notes": "", "created_at": "", "updated_at": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a contact - **Method:** `PUT` - **Path:** `/api-service/contacts/{id}` - **Operation ID:** `replaceContact` - **Tags:** Contacts Partial update: only the fields you send are updated, including with PUT, which is identical to PATCH. type is validated against the list of allowed types (otherwise 400). If no updatable field is sent, the API returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Contact ID `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json schema: `UpdateContact` — Partial update of a contact (all fields are optional) - **`company`** `string` - **`custom_type`** `string` - **`email`** `string`, format: `email` - **`first_name`** `string` - **`job_title`** `string` - **`last_name`** `string` - **`notes`** `string` - **`phone`** `string` - **`type`** `string`, possible values: `"banker", "lawyer", "appraiser", "insurance", "contractor", "other"` — Contact type. When other, details can be given in custom_type **Example:** ```json { "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": "", "notes": "" } ``` #### Responses ##### Status: 200 The updated contact ###### Content-Type: application/json *Schema `Contact` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": null, "notes": "", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a contact - **Method:** `PATCH` - **Path:** `/api-service/contacts/{id}` - **Operation ID:** `updateContact` - **Tags:** Contacts Partial update: only the fields you send are updated, including with PUT, which is identical to PATCH. type is validated against the list of allowed types (otherwise 400). If no updatable field is sent, the API returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Contact ID `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json *Schema `UpdateContact` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": "", "notes": "" } ``` #### Responses ##### Status: 200 The updated contact ###### Content-Type: application/json *Schema `Contact` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": null, "notes": "", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Delete a contact - **Method:** `DELETE` - **Path:** `/api-service/contacts/{id}` - **Operation ID:** `deleteContact` - **Tags:** Contacts Soft delete: the contact is no longer returned in queries. A contact that is linked to a mortgage file cannot be deleted; the API returns 409 with related_mortgages_count. Unlink the contact from its mortgage files in the app first (the API does not provide an unlink operation). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Contact ID `string`, format: `uuid` #### Responses ##### Status: 200 Contact deleted ###### Content-Type: application/json *Schema `DeleteResult` is shown above.* **Example: default** ```json { "success": true, "message": "Contact deleted successfully" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 The contact is linked to mortgage files. The number of links is returned in related_mortgages_count ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Cannot delete contact", "details": "This contact is linked to active mortgage files. You must unlink them first.", "status": 409, "related_mortgages_count": 1 } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List tasks - **Method:** `GET` - **Path:** `/api-service/tasks` - **Operation ID:** `getTasks` - **Tags:** Tasks Returns the organization's tasks (excluding deleted tasks), each with a summary of its linked entity (mortgage_file / lead / customer, or null). Sorted by due_date in ascending order (tasks without a due date last), then from newest to oldest. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `mortgage_file_id` - **In:** `query` Only tasks linked to this mortgage file `string`, format: `uuid` ##### `lead_id` - **In:** `query` Only tasks linked to this lead `string`, format: `uuid` ##### `customer_id` - **In:** `query` Only tasks linked to this customer `string`, format: `uuid` ##### `standalone` - **In:** `query` true - only standalone tasks that are not linked to a mortgage file, lead, or customer `boolean`, default: `false` ##### `status` - **In:** `query` Filter by status `string`, possible values: `"open", "in_progress", "completed", "cancelled"` ##### `priority` - **In:** `query` Filter by priority `string`, possible values: `"low", "medium", "high"` ##### `assigned_to` - **In:** `query` Filter by the user the task is assigned to `string`, format: `uuid` ##### `unassigned` - **In:** `query` true - only tasks that are not assigned to a user `boolean`, default: `false` ##### `search` - **In:** `query` Partial, case-insensitive search across title and description. The characters , ( ) % \_ \ " ' are removed from the search term before searching. `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 List of tasks ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `Task` — A task. It can be linked to a mortgage file, a lead, or a customer, or be standalone (all \*\_id fields can be null). The response includes an object for the linked entity (\`mortgage_file\`/\`lead\`/\`customer\`) when one exists. - **`assigned_to`** `string | null`, format: `uuid` - **`completed_at`** `string | null`, format: `date-time` - **`completed_by`** `string | null`, format: `uuid` - **`created_at`** `string`, format: `date-time` - **`customer`** `object | null` — Details of the linked customer (null if not linked) - **`first_name`** `string | null` - **`id`** `string`, format: `uuid` - **`id_number`** `string | null` - **`last_name`** `string | null` - **`customer_id`** `string | null`, format: `uuid` - **`description`** `string | null` - **`due_date`** `string | null`, format: `date-time` — Due date - **`id`** `string`, format: `uuid` - **`is_favorite`** `boolean` - **`lead`** `object | null` — Details of the linked lead (null if not linked) - **`first_name`** `string | null` - **`id`** `string`, format: `uuid` - **`last_name`** `string | null` - **`phone`** `string | null` - **`status`** `string | null` - **`lead_id`** `string | null`, format: `uuid` - **`mortgage_file`** `object | null` — Details of the linked file (null if not linked) - **`file_number`** `string | null` - **`id`** `string`, format: `uuid` - **`status`** `string | null` - **`title`** `string | null` - **`mortgage_file_id`** `string | null`, format: `uuid` - **`organization_id`** `string`, format: `uuid` - **`parent_task_id`** `string | null`, format: `uuid` - **`priority`** `string`, possible values: `"low", "medium", "high"` - **`progress`** `number`, minimum: `0`, maximum: `100` — Progress percentage - **`status`** `string`, possible values: `"open", "in_progress", "completed", "cancelled"` - **`title`** `string` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a task - **Method:** `POST` - **Path:** `/api-service/tasks` - **Operation ID:** `createTask` - **Tags:** Tasks Creates a task. You can link it to a mortgage file, lead, and/or customer (mortgage_file_id / lead_id / customer_id), or create a standalone task without any of them. - Required: title (non-empty). Otherwise, the API returns 400. - Every entity ID you send must belong to an active record in the organization. Otherwise, the API returns 400. - Defaults: status=open, priority=medium. - status must be one of open, in_progress, completed, cancelled (otherwise 400); the legacy value done is accepted as completed. completed also sets completed_at. - parent_task_id must be a task in the organization (otherwise 400). - An assigned_to value that is not the ID of an active user in the organization is ignored. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Request Body Task details **Required:** `true` ##### Content-Type: application/json schema: `CreateTask` — Data for creating a task. You can link the task to a file, a lead, and/or a customer, or leave all three IDs empty to create a standalone task. Fields not listed here are ignored. - **`title` (required)** `string` — Task title (required, must not be empty) - **`assigned_to`** `string`, format: `uuid` — ID of a user in the organization. An ID that does not belong to an active user in the organization is ignored, and the task is created unassigned - **`customer_id`** `string | null`, format: `uuid` — Customer to link. Ignored on the /mortgage-files/{id}/tasks path - **`description`** `string` - **`due_date`** `string`, format: `date-time` — Due date (ISO 8601) - **`is_favorite`** `boolean` - **`lead_id`** `string | null`, format: `uuid` — Lead to link. Ignored on the /mortgage-files/{id}/tasks path - **`mortgage_file_id`** `string | null`, format: `uuid` — File to link. On the /mortgage-files/{id}/tasks path, it is taken from the path and the value here is ignored - **`parent_task_id`** `string`, format: `uuid` — ID of the parent task (for a subtask) - **`priority`** `string`, possible values: `"low", "medium", "high"`, default: `"medium"` - **`progress`** `number`, minimum: `0`, maximum: `100` — Progress percentage - **`status`** `string`, possible values: `"open", "in_progress", "completed", "cancelled"`, default: `"open"` **Example: default** ```json { "title": "Collect pay slips", "description": "Last three pay slips for both borrowers", "due_date": "2026-11-01T09:00:00+00:00", "priority": "high", "mortgage_file_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f" } ``` #### Responses ##### Status: 201 Task created (including a summary of the linked entity) ###### Content-Type: application/json *Schema `Task` is shown above.* **Example: default** ```json { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "organization_id": "0b8e1f2a-7c3d-4a5b-9e6f-2a3b4c5d6e7f", "mortgage_file_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "lead_id": null, "customer_id": null, "title": "Collect pay slips", "description": "Last three pay slips for both borrowers", "status": "open", "priority": "high", "due_date": "2026-11-01T09:00:00+00:00", "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": false, "completed_at": null, "created_at": "2026-10-14T08:15:22.481234+00:00", "updated_at": "2026-10-14T08:15:22.481234+00:00", "mortgage_file": { "id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "file_number": "2026-0042", "title": "Apartment purchase - Cohen family", "status": "setup" }, "lead": null, "customer": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a task - **Method:** `GET` - **Path:** `/api-service/tasks/{taskId}` - **Operation ID:** `getTask` - **Tags:** Tasks Returns a task by ID, including a summary of its linked entity. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `taskId` required - **In:** `path` Task ID `string`, format: `uuid` #### Responses ##### Status: 200 The task ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a task - **Method:** `PUT` - **Path:** `/api-service/tasks/{taskId}` - **Operation ID:** `updateTask` - **Tags:** Tasks Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. This path also lets you replace or unlink (null) the linked entity: mortgage_file_id, lead_id, customer_id. Any ID you send must belong to an active record in the organization (otherwise 400). status follows the same rules as in creation: moving to completed sets completed_at, and moving away from completed clears it. parent_task_id must be another task in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `taskId` required - **In:** `path` Task ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateTask` — A partial update of a task: only the fields that are sent are updated. Replacing or unlinking (null) the linked entity is supported only via PUT/PATCH /tasks/{taskId}; on the /mortgage-files/{id}/tasks/{taskId} path, these fields are ignored. - **`assigned_to`** `string | null`, format: `uuid` — ID of a user in the organization. null or an empty string removes the assignment; an ID that does not belong to an active user in the organization is ignored - **`customer_id`** `string | null`, format: `uuid` — Customer to link (null unlinks it). Must be an active customer in the organization - **`description`** `string` - **`due_date`** `string | null`, format: `date-time` — Due date (ISO 8601) - **`is_favorite`** `boolean` - **`lead_id`** `string | null`, format: `uuid` — Lead to link (null unlinks it). Must be a lead in the organization - **`mortgage_file_id`** `string | null`, format: `uuid` — File to link (null unlinks it). Must be an active file in the organization - **`parent_task_id`** `string | null`, format: `uuid` — ID of the parent task - **`priority`** `string`, possible values: `"low", "medium", "high"` - **`progress`** `number`, minimum: `0`, maximum: `100` — Progress percentage - **`status`** `string`, possible values: `"open", "in_progress", "completed", "cancelled"` - **`title`** `string` **Example:** ```json { "title": "", "description": "", "due_date": null, "status": "open", "priority": "low", "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "mortgage_file_id": null, "lead_id": null, "customer_id": null } ``` #### Responses ##### Status: 200 The updated task ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a task - **Method:** `PATCH` - **Path:** `/api-service/tasks/{taskId}` - **Operation ID:** `patchTask` - **Tags:** Tasks Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. This path also lets you replace or unlink (null) the linked entity: mortgage_file_id, lead_id, customer_id. Any ID you send must belong to an active record in the organization (otherwise 400). status follows the same rules as in creation: moving to completed sets completed_at, and moving away from completed clears it. parent_task_id must be another task in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `taskId` required - **In:** `path` Task ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateTask` is shown above.* **Example:** ```json { "title": "", "description": "", "due_date": null, "status": "open", "priority": "low", "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "mortgage_file_id": null, "lead_id": null, "customer_id": null } ``` #### Responses ##### Status: 200 The updated task ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a task's status - **Method:** `PATCH` - **Path:** `/api-service/tasks/{taskId}/status` - **Operation ID:** `patchTaskStatusTopLevel` - **Tags:** Tasks Updates only the status field: open, in_progress, completed or cancelled (the legacy value done is accepted as completed). Moving to completed sets completed_at, and moving away from completed clears it. A missing or unknown status returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `taskId` required - **In:** `path` Task ID `string`, format: `uuid` #### Request Body The new status **Required:** `true` ##### Content-Type: application/json - **`status` (required)** `string`, possible values: `"open", "in_progress", "completed", "cancelled"` **Example: default** ```json { "status": "completed" } ``` #### Responses ##### Status: 200 The updated task ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a mortgage file's timeline - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/timeline` - **Operation ID:** `getMortgageFileTimeline` - **Tags:** Timeline Returns the mortgage file's timeline events, newest first, with pagination. Read-only. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `event_type` - **In:** `query` Filter by event type: a value from the system's event types, for example status_updated, note_added, task_created, task_completed, charge_created, payment_received `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 Timeline events ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `TimelineEvent` — A timeline event (file created, status changed, etc.) - **`created_at`** `string`, format: `date-time` - **`created_by`** `string | null`, format: `uuid` - **`description`** `string | null` - **`entity_id`** `string`, format: `uuid` - **`entity_type`** `string` - **`event_type`** `string` — Event type (for example status_updated, note_added, task_created, file_created) - **`id`** `string`, format: `uuid` - **`metadata`** `object` — Type-specific metadata (old_status/new_status, etc.) - **`organization_id`** `string`, format: `uuid` - **`title`** `string` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "event_type": "", "title": "", "description": null, "metadata": {}, "created_by": null, "created_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a mortgage file's status history - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/status-history` - **Operation ID:** `getMortgageFileStatusHistory` - **Tags:** Timeline Same as /timeline, filtered to status change events (event type status_updated and, for older records, status_change). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 Timeline events ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** *Schema `TimelineEvent` is shown above.* **Example:** ```json { "data": [ { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "event_type": "", "title": "", "description": null, "metadata": {}, "created_by": null, "created_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's tasks - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/tasks` - **Operation ID:** `getMortgageFileTasks` - **Tags:** Tasks Same as GET /tasks, limited to the mortgage file's tasks. Sorted by due_date in ascending order (tasks without a due date last), then from newest to oldest. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `status` - **In:** `query` Filter by status `string`, possible values: `"open", "in_progress", "completed", "cancelled"` ##### `priority` - **In:** `query` Filter by priority `string`, possible values: `"low", "medium", "high"` ##### `assigned_to` - **In:** `query` Filter by the user the task is assigned to `string`, format: `uuid` ##### `unassigned` - **In:** `query` true - only tasks that are not assigned to a user `boolean`, default: `false` ##### `search` - **In:** `query` Partial, case-insensitive search across title and description. The characters , ( ) % \_ \ " ' are removed from the search term before searching. `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The mortgage file's tasks ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** *Schema `Task` is shown above.* **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a task in a mortgage file - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/tasks` - **Operation ID:** `createMortgageFileTask` - **Tags:** Tasks Creates a task linked to the mortgage file in the path. title is required (otherwise 400). mortgage_file_id, lead_id, and customer_id in the request body are ignored. status and parent_task_id follow the same rules as in POST /tasks. Defaults: status=open, priority=medium. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body Task details **Required:** `true` ##### Content-Type: application/json *Schema `CreateTask` is shown above.* **Example:** ```json { "title": "", "description": "", "due_date": "", "status": "open", "priority": "medium", "assigned_to": "", "parent_task_id": "", "progress": 0, "is_favorite": true, "mortgage_file_id": null, "lead_id": null, "customer_id": null } ``` #### Responses ##### Status: 201 Task created ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a mortgage file task - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/tasks/{taskId}` - **Operation ID:** `getMortgageFileTask` - **Tags:** Tasks Returns a task of the mortgage file by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `taskId` required - **In:** `path` Task ID `string`, format: `uuid` #### Responses ##### Status: 200 The task ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a mortgage file task - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/tasks/{taskId}` - **Operation ID:** `updateMortgageFileTask` - **Tags:** Tasks Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. This path cannot change the linked entities (mortgage_file_id, lead_id, customer_id); to do so, use PUT /tasks/{taskId}. status follows the same rules as in creation: moving to completed sets completed_at, and moving away from completed clears it. parent_task_id must be another task in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `taskId` required - **In:** `path` Task ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateTask` is shown above.* **Example:** ```json { "title": "", "description": "", "due_date": null, "status": "open", "priority": "low", "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "mortgage_file_id": null, "lead_id": null, "customer_id": null } ``` #### Responses ##### Status: 200 The updated task ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a mortgage file task - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/tasks/{taskId}` - **Operation ID:** `patchMortgageFileTask` - **Tags:** Tasks Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. This path cannot change the linked entities (mortgage_file_id, lead_id, customer_id); to do so, use PUT /tasks/{taskId}. status follows the same rules as in creation: moving to completed sets completed_at, and moving away from completed clears it. parent_task_id must be another task in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `taskId` required - **In:** `path` Task ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateTask` is shown above.* **Example:** ```json { "title": "", "description": "", "due_date": null, "status": "open", "priority": "low", "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "mortgage_file_id": null, "lead_id": null, "customer_id": null } ``` #### Responses ##### Status: 200 The updated task ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a mortgage file task's status - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/tasks/{taskId}/status` - **Operation ID:** `patchMortgageFileTaskStatus` - **Tags:** Tasks Updates only the status field: open, in_progress, completed or cancelled (the legacy value done is accepted as completed). Moving to completed sets completed_at, and moving away from completed clears it. A missing or unknown status returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `taskId` required - **In:** `path` Task ID `string`, format: `uuid` #### Request Body The new status **Required:** `true` ##### Content-Type: application/json - **`status` (required)** `string`, possible values: `"open", "in_progress", "completed", "cancelled"` **Example: default** ```json { "status": "completed" } ``` #### Responses ##### Status: 200 The updated task ###### Content-Type: application/json *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's notes - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/notes` - **Operation ID:** `getMortgageFileNotes` - **Tags:** Notes Returns pinned notes (is_pinned) first, followed by the rest from newest to oldest. Deleted notes are excluded. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `search` - **In:** `query` Partial, case-insensitive search across title and content. The characters , ( ) % \_ \ " ' are removed from the search term before searching. `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The mortgage file's notes ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `Note` — A note on a mortgage file (entity_notes) - **`completed_at`** `string | null`, format: `date-time` - **`content`** `string` - **`created_at`** `string`, format: `date-time` - **`entity_id`** `string`, format: `uuid` - **`entity_type`** `string` - **`id`** `string`, format: `uuid` - **`is_completed`** `boolean` - **`is_locked`** `boolean` — A locked note can be updated only in a request that also unlocks it (is_locked: false) - **`is_pinned`** `boolean` - **`organization_id`** `string`, format: `uuid` - **`title`** `string | null` - **`updated_at`** `string | null`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": null, "content": "", "is_pinned": true, "is_locked": true, "is_completed": true, "completed_at": null, "created_at": "", "updated_at": null } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a note in a mortgage file - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/notes` - **Operation ID:** `createMortgageFileNote` - **Tags:** Notes content is required and must not be empty. Otherwise, the API returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body Note details **Required:** `true` ##### Content-Type: application/json schema: `CreateNote` — Data for creating a note. content is required. - **`content` (required)** `string` - **`is_completed`** `boolean`, default: `false` - **`is_locked`** `boolean`, default: `false` - **`is_pinned`** `boolean`, default: `false` - **`title`** `string` **Example: default** ```json { "title": "Call with the bank", "content": "The bank requested an up-to-date balance confirmation for the existing mortgage", "is_pinned": true } ``` #### Responses ##### Status: 201 Note created ###### Content-Type: application/json *Schema `Note` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": null, "content": "", "is_pinned": true, "is_locked": true, "is_completed": true, "completed_at": null, "created_at": "", "updated_at": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a note - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/notes/{noteId}` - **Operation ID:** `getMortgageFileNote` - **Tags:** Notes Returns a note of the mortgage file by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `noteId` required - **In:** `path` Note ID `string`, format: `uuid` #### Responses ##### Status: 200 The note ###### Content-Type: application/json *Schema `Note` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": null, "content": "", "is_pinned": true, "is_locked": true, "is_completed": true, "completed_at": null, "created_at": "", "updated_at": null } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a note - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/notes/{noteId}` - **Operation ID:** `updateMortgageFileNote` - **Tags:** Notes Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, the API returns 400. is_completed=true also sets completed_at. A locked note (is_locked=true) returns 409 unless the request unlocks it (is_locked: false); the unlock can be combined with other changes in the same request. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `noteId` required - **In:** `path` Note ID `string`, format: `uuid` #### Request Body Fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateNote` - **`content`** `string` - **`is_completed`** `boolean` - **`is_locked`** `boolean` - **`is_pinned`** `boolean` - **`title`** `string` **Example:** ```json { "title": "", "content": "", "is_pinned": true, "is_locked": true, "is_completed": true } ``` #### Responses ##### Status: 200 The updated note ###### Content-Type: application/json *Schema `Note` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": null, "content": "", "is_pinned": true, "is_locked": true, "is_completed": true, "completed_at": null, "created_at": "", "updated_at": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 The note is locked (is_locked=true) and the request does not unlock it ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Note is locked", "details": "Unlock the note before editing", "status": 409 } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a note - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/notes/{noteId}` - **Operation ID:** `patchMortgageFileNote` - **Tags:** Notes Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. Setting is_completed=true also sets completed_at. A locked note (is_locked=true) returns 409 unless the request unlocks it (is_locked: false); the unlock can be combined with other changes in the same request. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `noteId` required - **In:** `path` The note ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateNote` is shown above.* **Example:** ```json { "title": "", "content": "", "is_pinned": true, "is_locked": true, "is_completed": true } ``` #### Responses ##### Status: 200 The updated note ###### Content-Type: application/json *Schema `Note` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": null, "content": "", "is_pinned": true, "is_locked": true, "is_completed": true, "completed_at": null, "created_at": "", "updated_at": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 The note is locked (is_locked=true) and the request does not unlock it ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Note is locked", "details": "Unlock the note before editing", "status": 409 } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's contacts - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/contacts` - **Operation ID:** `getMortgageFileContacts` - **Tags:** File contacts Returns the active contact links for the mortgage file, newest first, each with the contact's details (contact). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The contact links ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `MortgageContactLink` — A link between a contact and a file (mortgage_contacts) - **`contact`** `object` — Contact details (joined) - **`company`** `string | null` - **`custom_type`** `string | null` - **`email`** `string | null` - **`first_name`** `string` - **`id`** `string`, format: `uuid` - **`job_title`** `string | null` - **`last_name`** `string` - **`phone`** `string | null` - **`type`** `string` - **`contact_id`** `string`, format: `uuid` - **`created_at`** `string`, format: `date-time` - **`id`** `string`, format: `uuid` - **`mortgage_file_id`** `string`, format: `uuid` - **`notes`** `string | null` - **`organization_id`** `string`, format: `uuid` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "contact_id": "", "notes": null, "contact": { "id": "", "first_name": "", "last_name": "", "type": "", "custom_type": null, "email": null, "phone": null, "company": null, "job_title": null }, "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Link a contact to a mortgage file - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/contacts` - **Operation ID:** `linkMortgageFileContact` - **Tags:** File contacts contact_id is required (otherwise 400) and must belong to an active contact in the organization (otherwise 404). If the contact is already linked to the mortgage file, returns 409 with the existing link's ID in existing_link_id. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`contact_id` (required)** `string`, format: `uuid` — The contact ID - **`notes`** `string` — Notes for the link **Example: default** ```json { "contact_id": "9e0f1a2b-3c4d-4e5f-a6b7-c8d9e0f1a2b3", "notes": "The banker handling the file" } ``` #### Responses ##### Status: 201 The link was created ###### Content-Type: application/json *Schema `MortgageContactLink` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "contact_id": "", "notes": null, "contact": { "id": "", "first_name": "", "last_name": "", "type": "", "custom_type": null, "email": null, "phone": null, "company": null, "job_title": null }, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 The contact is already linked to the mortgage file. The existing link's ID is returned in existing_link_id ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Contact already linked", "details": "Use PUT to update link notes", "status": 409, "existing_link_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a file contact's notes - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/contacts/{linkId}` - **Operation ID:** `updateMortgageFileContactLink` - **Tags:** File contacts Only notes can be updated (PUT and PATCH behave identically). A request without notes returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `linkId` required - **In:** `path` The link ID (the id from the mortgage file's contacts list, not the contact ID) `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`notes`** `string` — Notes for the link **Example: default** ```json { "notes": "The banker handling the file" } ``` #### Responses ##### Status: 200 The updated link ###### Content-Type: application/json *Schema `MortgageContactLink` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "contact_id": "", "notes": null, "contact": { "id": "", "first_name": "", "last_name": "", "type": "", "custom_type": null, "email": null, "phone": null, "company": null, "job_title": null }, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a file contact's notes - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/contacts/{linkId}` - **Operation ID:** `patchMortgageFileContactLink` - **Tags:** File contacts Only notes can be updated (PUT and PATCH behave identically). A request without notes returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `linkId` required - **In:** `path` The link ID (the id from the mortgage file's contacts list, not the contact ID) `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`notes`** `string` — Notes for the link **Example: default** ```json { "notes": "The banker handling the file" } ``` #### Responses ##### Status: 200 The updated link ###### Content-Type: application/json *Schema `MortgageContactLink` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "contact_id": "", "notes": null, "contact": { "id": "", "first_name": "", "last_name": "", "type": "", "custom_type": null, "email": null, "phone": null, "company": null, "job_title": null }, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's watchers - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/watchers` - **Operation ID:** `getMortgageFileWatchers` - **Tags:** Watchers Returns the users watching the mortgage file, newest first, each with the user's details (watcher). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The watchers ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `Watcher` — A user who watches a file (mortgage_file_watchers). Note: \`email\` is not available through the external API (the email address is stored in auth.users, separately from profiles). - **`created_at`** `string`, format: `date-time` - **`id`** `string`, format: `uuid` - **`mortgage_file_id`** `string`, format: `uuid` - **`organization_id`** `string`, format: `uuid` - **`watcher`** `object` — User details (joined from profiles) - **`first_name`** `string` - **`id`** `string`, format: `uuid` - **`last_name`** `string` - **`watcher_id`** `string`, format: `uuid` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "watcher_id": "", "watcher": { "id": "", "first_name": "", "last_name": "" }, "created_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Add a watcher to a mortgage file - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/watchers` - **Operation ID:** `addMortgageFileWatcher` - **Tags:** Watchers watcher_id is required (otherwise 400) and must be the ID of an active user in the organization (otherwise 404). If the user is already watching, returns 409 with the existing record's ID in existing_id. The API does not provide a remove operation. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`watcher_id` (required)** `string`, format: `uuid` — ID of the user (profile) who will watch the mortgage file **Example: default** ```json { "watcher_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a" } ``` #### Responses ##### Status: 201 The watcher was added ###### Content-Type: application/json *Schema `Watcher` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "watcher_id": "", "watcher": { "id": "", "first_name": "", "last_name": "" }, "created_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 The user is already watching the mortgage file. The existing record's ID is returned in existing_id ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Watcher already attached", "status": 409, "existing_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e" } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's documents - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/documents` - **Operation ID:** `getMortgageFileDocuments` - **Tags:** Documents Returns metadata for the customer's documents in the mortgage file, newest first. Read-only: file contents are not available through the API. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `borrower_id` - **In:** `query` Filter by borrower `string`, format: `uuid` ##### `category` - **In:** `query` Filter by category (exact match) `string` ##### `search` - **In:** `query` Partial, case-insensitive search on the original file name and category. The characters , ( ) % \_ \ " ' are stripped from the term before searching. `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The mortgage file's documents ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `ClientDocument` — A customer document (metadata only; the content is stored in Supabase Storage) - **`borrower_id`** `string | null`, format: `uuid` - **`category`** `string | null` - **`created_at`** `string`, format: `date-time` - **`drive_file_id`** `string | null` - **`drive_folder_id`** `string | null` - **`file_path`** `string` - **`file_size`** `integer | null` - **`file_type`** `string | null` - **`id`** `string`, format: `uuid` - **`mortgage_file_id`** `string`, format: `uuid` - **`needs_signature`** `boolean` - **`organization_id`** `string`, format: `uuid` - **`original_name`** `string` - **`stored_name`** `string` - **`uploaded_by_id`** `string | null`, format: `uuid` - **`uploaded_by_type`** `string`, possible values: `"borrower", "advisor"` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "original_name": "", "stored_name": "", "file_path": "", "file_size": null, "file_type": null, "category": null, "needs_signature": true, "uploaded_by_type": "borrower", "uploaded_by_id": null, "drive_folder_id": null, "drive_file_id": null, "created_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a document - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/documents/{docId}` - **Operation ID:** `getMortgageFileDocument` - **Tags:** Documents Returns the metadata of a document in the mortgage file by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `docId` required - **In:** `path` The document ID `string`, format: `uuid` #### Responses ##### Status: 200 The document ###### Content-Type: application/json *Schema `ClientDocument` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "original_name": "", "stored_name": "", "file_path": "", "file_size": null, "file_type": null, "category": null, "needs_signature": true, "uploaded_by_type": "borrower", "uploaded_by_id": null, "drive_folder_id": null, "drive_file_id": null, "created_at": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's signatures - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/signatures` - **Operation ID:** `getMortgageFileSignatures` - **Tags:** Signatures Returns the signature records for documents that belong to the mortgage file, newest first, each with the document's details (document). Read-only. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The signatures ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `DocumentSignature` — A signature on a document - **`borrower_id`** `string`, format: `uuid` - **`created_at`** `string`, format: `date-time` - **`document`** `object` — Document details (joined) - **`borrower_id`** `string | null`, format: `uuid` - **`file_path`** `string` - **`id`** `string`, format: `uuid` - **`mortgage_file_id`** `string`, format: `uuid` - **`original_name`** `string` - **`document_id`** `string`, format: `uuid` - **`id`** `string`, format: `uuid` - **`is_signed`** `boolean` - **`organization_id`** `string`, format: `uuid` - **`signature_date`** `string | null`, format: `date-time` - **`signed_at`** `string | null`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "document_id": "", "borrower_id": "", "is_signed": true, "signed_at": null, "signature_date": null, "document": { "id": "", "original_name": "", "mortgage_file_id": "", "borrower_id": null, "file_path": "" }, "created_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's generated documents - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/generated-documents` - **Operation ID:** `getMortgageFileGeneratedDocuments` - **Tags:** Generated documents Returns the documents generated from templates for the mortgage file, newest first. Read-only. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `status` - **In:** `query` Filter by document status `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The generated documents ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `GeneratedDocument` — A document generated from a template (generated_documents) - **`created_at`** `string`, format: `date-time` - **`document_name`** `string` - **`entity_id`** `string`, format: `uuid` - **`entity_type`** `string` - **`filled_content`** `string | null` - **`filled_variables`** `object` - **`id`** `string`, format: `uuid` - **`organization_id`** `string`, format: `uuid` - **`pdf_path`** `string | null` - **`signatures`** `array` **Items:** `object` - **`status`** `string` - **`template_id`** `string | null`, format: `uuid` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "template_id": null, "entity_type": "mortgage_file", "entity_id": "", "document_name": "", "filled_content": null, "filled_variables": {}, "signatures": [ {} ], "pdf_path": null, "status": "", "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a generated document - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/generated-documents/{docId}` - **Operation ID:** `getMortgageFileGeneratedDocument` - **Tags:** Generated documents Returns a document generated from a template for the mortgage file, by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `docId` required - **In:** `path` The generated document ID `string`, format: `uuid` #### Responses ##### Status: 200 The document ###### Content-Type: application/json *Schema `GeneratedDocument` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "template_id": null, "entity_type": "mortgage_file", "entity_id": "", "document_name": "", "filled_content": null, "filled_variables": {}, "signatures": [ {} ], "pdf_path": null, "status": "", "created_at": "", "updated_at": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's document statuses - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/document-statuses` - **Operation ID:** `getMortgageFileDocumentStatuses` - **Tags:** Document statuses Returns the tracking rows for documents requested from the mortgage file's borrowers (including documents for signature), newest first. Rows are created by the system; the API does not support creating or deleting them. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `status` - **In:** `query` Filter by status `string`, possible values: `"pending", "uploading", "under_review", "completed", "rejected"` ##### `borrower_id` - **In:** `query` Filter by borrower `string`, format: `uuid` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The document statuses ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `ClientDocumentStatus` — Status of a required document, per borrower - **`borrower_id`** `string | null`, format: `uuid` - **`created_at`** `string`, format: `date-time` - **`document_type_id`** `string` - **`document_type_title`** `string` - **`hide_from_client`** `boolean` - **`id`** `string`, format: `uuid` - **`mortgage_file_id`** `string`, format: `uuid` - **`notes`** `object` — Document metadata, including status_history - **`organization_id`** `string`, format: `uuid` - **`status`** `string`, possible values: `"pending", "uploading", "under_review", "completed", "rejected"` - **`updated_at`** `string`, format: `date-time` - **`upload_progress`** `integer`, minimum: `0`, maximum: `100` - **`uploaded_document_id`** `string | null`, format: `uuid` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "document_type_id": "", "document_type_title": "", "status": "pending", "uploaded_document_id": null, "upload_progress": 0, "notes": {}, "hide_from_client": true, "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a document status - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/document-statuses/{statusId}` - **Operation ID:** `updateMortgageFileDocumentStatus` - **Tags:** Document statuses Only status and notes can be updated (PUT and PATCH behave identically). If neither is sent, returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `statusId` required - **In:** `path` The status row ID `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`notes`** `object` — Replaces the entire stored notes object (including status_history) - **`status`** `string`, possible values: `"pending", "uploading", "under_review", "completed", "rejected"` — The new status **Example: default** ```json { "status": "completed" } ``` #### Responses ##### Status: 200 The updated status row ###### Content-Type: application/json *Schema `ClientDocumentStatus` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "document_type_id": "", "document_type_title": "", "status": "pending", "uploaded_document_id": null, "upload_progress": 0, "notes": {}, "hide_from_client": true, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a document status - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/document-statuses/{statusId}` - **Operation ID:** `patchMortgageFileDocumentStatus` - **Tags:** Document statuses Only status and notes can be updated (PUT and PATCH behave identically). If neither is sent, returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `statusId` required - **In:** `path` The status row ID `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`notes`** `object` — Replaces the entire stored notes object (including status_history) - **`status`** `string`, possible values: `"pending", "uploading", "under_review", "completed", "rejected"` — The new status **Example: default** ```json { "status": "completed" } ``` #### Responses ##### Status: 200 The updated status row ###### Content-Type: application/json *Schema `ClientDocumentStatus` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "document_type_id": "", "document_type_title": "", "status": "pending", "uploaded_document_id": null, "upload_progress": 0, "notes": {}, "hide_from_client": true, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's reminders - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/reminders` - **Operation ID:** `getMortgageFileReminders` - **Tags:** Reminders Returns the mortgage file's reminders, sorted by remind_at (earliest first). By default, only reminders that have not yet been sent or dismissed are returned. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `include_sent` - **In:** `query` If true, also includes reminders that have already been sent `boolean`, default: `false` ##### `include_dismissed` - **In:** `query` If true, also includes dismissed reminders `boolean`, default: `false` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The mortgage file's reminders ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `Reminder` — A reminder on a file (reminders) - **`channels`** `array` **Items:** `string` - **`created_at`** `string`, format: `date-time` - **`description`** `string | null` - **`dismissed_at`** `string | null`, format: `date-time` - **`entity_id`** `string`, format: `uuid` - **`entity_type`** `string` - **`id`** `string`, format: `uuid` - **`is_dismissed`** `boolean` - **`is_sent`** `boolean` - **`metadata`** `object` - **`organization_id`** `string`, format: `uuid` - **`recipient_user_id`** `string | null`, format: `uuid` — ID of the user who receives the reminder. Must be a user in the organization - **`remind_at`** `string`, format: `date-time` - **`sent_at`** `string | null`, format: `date-time` - **`title`** `string` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": "", "description": null, "remind_at": "", "channels": [ "notification", "email" ], "metadata": {}, "recipient_user_id": null, "is_sent": true, "sent_at": null, "is_dismissed": true, "dismissed_at": null, "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a reminder for a mortgage file - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/reminders` - **Operation ID:** `createMortgageFileReminder` - **Tags:** Reminders Required: title (non-empty) and remind_at (an ISO 8601 timestamp); otherwise returns 400. channels defaults to \["notification"]. recipient_user_id (optional) must be a user in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body The reminder details **Required:** `true` ##### Content-Type: application/json schema: `CreateReminder` - **`remind_at` (required)** `string`, format: `date-time` - **`title` (required)** `string` - **`channels`** `array` **Items:** `string` - **`description`** `string` - **`metadata`** `object` - **`recipient_user_id`** `string`, format: `uuid` — ID of the user who receives the reminder. Must be a user in the organization **Example: default** ```json { "title": "Follow up with the bank on the approval in principle", "remind_at": "2026-10-20T07:00:00+00:00", "recipient_user_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a" } ``` #### Responses ##### Status: 201 The reminder was created ###### Content-Type: application/json *Schema `Reminder` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": "", "description": null, "remind_at": "", "channels": [ "notification", "email" ], "metadata": {}, "recipient_user_id": null, "is_sent": true, "sent_at": null, "is_dismissed": true, "dismissed_at": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a reminder - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/reminders/{reminderId}` - **Operation ID:** `getMortgageFileReminder` - **Tags:** Reminders Returns a reminder of the mortgage file by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `reminderId` required - **In:** `path` The reminder ID `string`, format: `uuid` #### Responses ##### Status: 200 The reminder ###### Content-Type: application/json *Schema `Reminder` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": "", "description": null, "remind_at": "", "channels": [ "notification", "email" ], "metadata": {}, "recipient_user_id": null, "is_sent": true, "sent_at": null, "is_dismissed": true, "dismissed_at": null, "created_at": "", "updated_at": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a reminder - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/reminders/{reminderId}` - **Operation ID:** `updateMortgageFileReminder` - **Tags:** Reminders Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. Setting is_dismissed=true also sets dismissed_at. recipient_user_id, if sent, must be a user in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `reminderId` required - **In:** `path` The reminder ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateReminder` - **`channels`** `array` **Items:** `string` - **`description`** `string` - **`is_dismissed`** `boolean` - **`metadata`** `object` - **`recipient_user_id`** `string`, format: `uuid` — ID of the user who receives the reminder. Must be a user in the organization - **`remind_at`** `string`, format: `date-time` - **`title`** `string` **Example:** ```json { "title": "", "description": "", "remind_at": "", "channels": [ "" ], "metadata": {}, "recipient_user_id": "", "is_dismissed": true } ``` #### Responses ##### Status: 200 The updated reminder ###### Content-Type: application/json *Schema `Reminder` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": "", "description": null, "remind_at": "", "channels": [ "notification", "email" ], "metadata": {}, "recipient_user_id": null, "is_sent": true, "sent_at": null, "is_dismissed": true, "dismissed_at": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a reminder - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/reminders/{reminderId}` - **Operation ID:** `patchMortgageFileReminder` - **Tags:** Reminders Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. Setting is_dismissed=true also sets dismissed_at. recipient_user_id, if sent, must be a user in the organization (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `reminderId` required - **In:** `path` The reminder ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateReminder` is shown above.* **Example:** ```json { "title": "", "description": "", "remind_at": "", "channels": [ "" ], "metadata": {}, "recipient_user_id": "", "is_dismissed": true } ``` #### Responses ##### Status: 200 The updated reminder ###### Content-Type: application/json *Schema `Reminder` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": "", "description": null, "remind_at": "", "channels": [ "notification", "email" ], "metadata": {}, "recipient_user_id": null, "is_sent": true, "sent_at": null, "is_dismissed": true, "dismissed_at": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's charges - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/charges` - **Operation ID:** `getMortgageFileCharges` - **Tags:** Charges Returns the mortgage file's charges, sorted by due_date in ascending order (charges without a date come last), then newest first. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `status` - **In:** `query` Filter by status `string`, possible values: `"pending", "partial", "paid", "cancelled"` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The mortgage file's charges ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `MortgageCharge` — A charge (payment request) on a file. The response may include additional payment-processing integration columns that are not documented here. - **`amount`** `number` - **`created_at`** `string`, format: `date-time` - **`description`** `string | null` - **`document_is_cancelled`** `boolean` - **`due_date`** `string | null`, format: `date` — Collection date. For a charge linked to a milestone, it may be set automatically - see due_date_source - **`due_date_source`** `string`, possible values: `"manual", "milestone"`, readOnly — Source of the collection date (set by the system): manual - entered manually and never overwritten automatically; milestone - set automatically when the linked milestone is completed - **`external_document_id`** `string | null` — When set, the charge is locked for editing - **`external_document_number`** `string | null` - **`external_document_type`** `string | null` - **`external_document_url`** `string | null` - **`external_provider`** `string | null` - **`id`** `string`, format: `uuid` - **`includes_vat`** `boolean` - **`is_ancillary_charge`** `boolean` — true = an ancillary charge (for example a Land Registry (Tabu) extract or courier fees); false = a advisory fee - **`item_name`** `string` - **`milestone_due_offset_days`** `integer` — Number of days after the milestone is completed on which the collection date is set (0 = the completion date) - **`milestone_id`** `string | null` — ID of the milestone the charge is linked to (an ID from the organization's milestone configuration, or the ID of a file-specific custom milestone). Always sent together with milestone_status_key - **`milestone_status_key`** `string | null` — Key of the status that the linked milestone belongs to. Always sent together with milestone_id - **`mortgage_file_id`** `string`, format: `uuid` - **`notes`** `string | null` - **`organization_id`** `string`, format: `uuid` - **`status`** `string`, possible values: `"pending", "partial", "paid", "cancelled"` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "item_name": "", "description": null, "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": null, "due_date_source": "manual", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1, "status": "pending", "notes": null, "external_document_id": null, "external_document_number": null, "external_document_type": null, "external_document_url": null, "external_provider": null, "document_is_cancelled": true, "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a charge - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/charges` - **Operation ID:** `createMortgageFileCharge` - **Tags:** Charges Required: item_name (non-empty) and amount (a non-negative number); otherwise returns 400. Defaults: status=pending, includes_vat=true, is_ancillary_charge=false, milestone_due_offset_days=0. **Milestone link:** milestone_id and milestone_status_key together identify a milestone in the mortgage file. Send both or neither; sending only one returns 400 (Invalid milestone link). When the linked milestone is marked as completed, due_date is set automatically to the completion date + milestone_due_offset_days (for charges with status pending or partial), and linking to a milestone that is already completed sets the date immediately. A manually entered date is never overwritten; the source of the date is shown in due_date_source. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body The charge details **Required:** `true` ##### Content-Type: application/json schema: `CreateMortgageCharge` — Data for creating a charge. milestone_id and milestone_status_key must be sent together or not at all; otherwise the request returns 400. - **`amount` (required)** `number`, minimum: `0` — Amount (a non-negative number) - **`item_name` (required)** `string` — Item name (required, non-empty) - **`description`** `string` - **`due_date`** `string`, format: `date` — Collection date (YYYY-MM-DD) - **`includes_vat`** `boolean`, default: `true` — Whether the amount includes VAT - **`is_ancillary_charge`** `boolean`, default: `false` — true = ancillary charge (e.g. a Land Registry (Tabu) extract or courier fees); false = advisory fee - **`milestone_due_offset_days`** `integer`, default: `0` — Number of days after the milestone is completed on which the collection date is set (0 = the completion date) - **`milestone_id`** `string` — ID of the milestone to link. Must be sent together with milestone_status_key - **`milestone_status_key`** `string` — Status key of the milestone. Must be sent together with milestone_id - **`notes`** `string` - **`status`** `string`, possible values: `"pending", "partial", "paid", "cancelled"`, default: `"pending"` **Example: default** ```json { "item_name": "Advisory fee - stage 2", "amount": 4500, "includes_vat": true, "is_ancillary_charge": false, "milestone_id": "8f9a0b1c-2d3e-4f5a-9b6c-7d8e9f0a1b2c", "milestone_status_key": "pending_approval", "milestone_due_offset_days": 3 } ``` #### Responses ##### Status: 201 The charge was created ###### Content-Type: application/json *Schema `MortgageCharge` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "item_name": "", "description": null, "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": null, "due_date_source": "manual", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1, "status": "pending", "notes": null, "external_document_id": null, "external_document_number": null, "external_document_type": null, "external_document_url": null, "external_provider": null, "document_is_cancelled": true, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a charge - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/charges/{chargeId}` - **Operation ID:** `getMortgageFileCharge` - **Tags:** Charges Returns a charge of the mortgage file by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `chargeId` required - **In:** `path` The charge ID `string`, format: `uuid` #### Responses ##### Status: 200 The charge ###### Content-Type: application/json *Schema `MortgageCharge` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "item_name": "", "description": null, "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": null, "due_date_source": "manual", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1, "status": "pending", "notes": null, "external_document_id": null, "external_document_number": null, "external_document_type": null, "external_document_url": null, "external_provider": null, "document_is_cancelled": true, "created_at": "", "updated_at": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a charge - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/charges/{chargeId}` - **Operation ID:** `updateMortgageFileCharge` - **Tags:** Charges Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. A charge for which an external document has been issued (external_document_id) is locked for editing and returns 409. The both-or-neither rule for the milestone link is evaluated against the merged result (the stored values combined with the request): you can change both together, or remove the link by setting both to null. Updating due_date through the API marks it as manual (due_date_source=manual). amount, if sent, must be a non-negative number (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `chargeId` required - **In:** `path` The charge ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateMortgageCharge` — Partial update of a charge. The milestone-link pairing rule is evaluated against the merged result (the stored values combined with the request); otherwise the request returns 400. - **`amount`** `number` — Amount - **`description`** `string` - **`due_date`** `string`, format: `date` — Collection date (YYYY-MM-DD). Updating it through the API marks it as manual (due_date_source=manual) - **`includes_vat`** `boolean` — Whether the amount includes VAT - **`is_ancillary_charge`** `boolean` — true = ancillary charge (e.g. a Land Registry (Tabu) extract or courier fees); false = advisory fee - **`item_name`** `string` — Item name - **`milestone_due_offset_days`** `integer` — Number of days after the milestone is completed on which the collection date is set (0 = the completion date) - **`milestone_id`** `string | null` — ID of the milestone to link. Setting both link fields to null removes the link - **`milestone_status_key`** `string | null` — Status key of the milestone. Setting both link fields to null removes the link - **`notes`** `string` - **`status`** `string`, possible values: `"pending", "partial", "paid", "cancelled"` **Example:** ```json { "item_name": "", "description": "", "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": "", "status": "pending", "notes": "", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1 } ``` #### Responses ##### Status: 200 The updated charge ###### Content-Type: application/json *Schema `MortgageCharge` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "item_name": "", "description": null, "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": null, "due_date_source": "manual", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1, "status": "pending", "notes": null, "external_document_id": null, "external_document_number": null, "external_document_type": null, "external_document_url": null, "external_provider": null, "document_is_cancelled": true, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 An external document (external_document_id) has already been issued for the charge, so it is locked for editing ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Charge has an issued document", "details": "Cannot edit a charge after an external document was issued; cancel via the billing integration instead", "status": 409 } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a charge - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/charges/{chargeId}` - **Operation ID:** `patchMortgageFileCharge` - **Tags:** Charges Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. A charge for which an external document has been issued (external_document_id) is locked for editing and returns 409. The both-or-neither rule for the milestone link is evaluated against the merged result (the stored values combined with the request): you can change both together, or remove the link by setting both to null. Updating due_date through the API marks it as manual (due_date_source=manual). amount, if sent, must be a non-negative number (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `chargeId` required - **In:** `path` The charge ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateMortgageCharge` is shown above.* **Example:** ```json { "item_name": "", "description": "", "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": "", "status": "pending", "notes": "", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1 } ``` #### Responses ##### Status: 200 The updated charge ###### Content-Type: application/json *Schema `MortgageCharge` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "item_name": "", "description": null, "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": null, "due_date_source": "manual", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1, "status": "pending", "notes": null, "external_document_id": null, "external_document_number": null, "external_document_type": null, "external_document_url": null, "external_provider": null, "document_is_cancelled": true, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 An external document (external_document_id) has already been issued for the charge, so it is locked for editing ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Charge has an issued document", "details": "Cannot edit a charge after an external document was issued; cancel via the billing integration instead", "status": 409 } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's payments - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/payments` - **Operation ID:** `getMortgageFilePayments` - **Tags:** Payments Returns the mortgage file's payments, sorted by payment_date, newest first. Cancelled payments are excluded by default. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `charge_id` - **In:** `query` Filter by charge `string`, format: `uuid` ##### `include_cancelled` - **In:** `query` If true, also includes cancelled payments `boolean`, default: `false` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The mortgage file's payments ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `MortgagePayment` — A payment received (mortgage_payments) - **`amount`** `number` - **`cancelled_at`** `string | null`, format: `date-time` - **`charge_id`** `string | null`, format: `uuid` - **`created_at`** `string`, format: `date-time` - **`external_document_id`** `string | null` — When set, the payment is locked for editing - **`external_document_number`** `string | null` - **`external_document_url`** `string | null` - **`id`** `string`, format: `uuid` - **`is_cancelled`** `boolean` - **`mortgage_file_id`** `string`, format: `uuid` - **`notes`** `string | null` - **`organization_id`** `string`, format: `uuid` - **`payment_date`** `string`, format: `date` - **`payment_method`** `string | null` - **`payment_source`** `string` - **`receipt_number`** `string | null` - **`reference_number`** `string | null` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "charge_id": null, "amount": 1, "payment_date": "", "payment_source": "", "payment_method": null, "reference_number": null, "receipt_number": null, "notes": null, "is_cancelled": true, "cancelled_at": null, "external_document_id": null, "external_document_number": null, "external_document_url": null, "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Record a payment - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/payments` - **Operation ID:** `createMortgageFilePayment` - **Tags:** Payments Required: amount (a positive number), payment_date (YYYY-MM-DD), and payment_source; otherwise returns 400. charge_id (optional) must be a charge of the same mortgage file; otherwise returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body The payment details **Required:** `true` ##### Content-Type: application/json schema: `CreateMortgagePayment` - **`amount` (required)** `number`, exclusiveMinimum: `0` — Payment amount (a positive number) - **`payment_date` (required)** `string`, format: `date` - **`payment_source` (required)** `string` - **`charge_id`** `string`, format: `uuid` — Optional: the specific charge this payment is for - **`notes`** `string` - **`payment_method`** `string` - **`receipt_number`** `string` - **`reference_number`** `string` **Example:** ```json { "charge_id": "", "amount": 1, "payment_date": "", "payment_source": "", "payment_method": "", "reference_number": "", "receipt_number": "", "notes": "" } ``` #### Responses ##### Status: 201 The payment was recorded ###### Content-Type: application/json *Schema `MortgagePayment` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "charge_id": null, "amount": 1, "payment_date": "", "payment_source": "", "payment_method": null, "reference_number": null, "receipt_number": null, "notes": null, "is_cancelled": true, "cancelled_at": null, "external_document_id": null, "external_document_number": null, "external_document_url": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a payment - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/payments/{paymentId}` - **Operation ID:** `getMortgageFilePayment` - **Tags:** Payments Returns a payment of the mortgage file by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `paymentId` required - **In:** `path` The payment ID `string`, format: `uuid` #### Responses ##### Status: 200 The payment ###### Content-Type: application/json *Schema `MortgagePayment` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "charge_id": null, "amount": 1, "payment_date": "", "payment_source": "", "payment_method": null, "reference_number": null, "receipt_number": null, "notes": null, "is_cancelled": true, "cancelled_at": null, "external_document_id": null, "external_document_number": null, "external_document_url": null, "created_at": "", "updated_at": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a payment - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/payments/{paymentId}` - **Operation ID:** `updateMortgageFilePayment` - **Tags:** Payments Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. A payment that has been cancelled, or for which a receipt has been issued (external_document_id), is locked for editing and returns 409. amount, if sent, must be a positive number, and charge_id must be a charge of the same mortgage file (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `paymentId` required - **In:** `path` The payment ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateMortgagePayment` - **`amount`** `number` — Payment amount - **`charge_id`** `string`, format: `uuid` — The charge this payment is associated with - **`notes`** `string` - **`payment_date`** `string`, format: `date` - **`payment_method`** `string` - **`payment_source`** `string` - **`receipt_number`** `string` - **`reference_number`** `string` **Example:** ```json { "charge_id": "", "amount": 1, "payment_date": "", "payment_source": "", "payment_method": "", "reference_number": "", "receipt_number": "", "notes": "" } ``` #### Responses ##### Status: 200 The updated payment ###### Content-Type: application/json *Schema `MortgagePayment` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "charge_id": null, "amount": 1, "payment_date": "", "payment_source": "", "payment_method": null, "reference_number": null, "receipt_number": null, "notes": null, "is_cancelled": true, "cancelled_at": null, "external_document_id": null, "external_document_number": null, "external_document_url": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 The payment has been cancelled, or a receipt has been issued for it (external_document_id), so it is locked for editing ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Payment is cancelled", "details": "Cannot update a cancelled payment", "status": 409 } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a payment - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/payments/{paymentId}` - **Operation ID:** `patchMortgageFilePayment` - **Tags:** Payments Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. A payment that has been cancelled, or for which a receipt has been issued (external_document_id), is locked for editing and returns 409. amount, if sent, must be a positive number, and charge_id must be a charge of the same mortgage file (otherwise 400). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `paymentId` required - **In:** `path` The payment ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateMortgagePayment` is shown above.* **Example:** ```json { "charge_id": "", "amount": 1, "payment_date": "", "payment_source": "", "payment_method": "", "reference_number": "", "receipt_number": "", "notes": "" } ``` #### Responses ##### Status: 200 The updated payment ###### Content-Type: application/json *Schema `MortgagePayment` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "charge_id": null, "amount": 1, "payment_date": "", "payment_source": "", "payment_method": null, "reference_number": null, "receipt_number": null, "notes": null, "is_cancelled": true, "cancelled_at": null, "external_document_id": null, "external_document_number": null, "external_document_url": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 409 The payment has been cancelled, or a receipt has been issued for it (external_document_id), so it is locked for editing ###### Content-Type: application/json *Schema `ErrorResponse` is shown above.* **Example: default** ```json { "error": "Payment is cancelled", "details": "Cannot update a cancelled payment", "status": 409 } ``` ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's analyses - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/analysis` - **Operation ID:** `getMortgageFileAnalyses` - **Tags:** File analysis Returns the analyses saved on the mortgage file, newest first. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The mortgage file's analyses ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `MortgageAnalysis` — A saved file analysis (mortgage_analysis) - **`analysis_data`** `object` — Analysis content (free-form jsonb) - **`created_at`** `string`, format: `date-time` - **`id`** `string`, format: `uuid` - **`mortgage_file_id`** `string`, format: `uuid` - **`organization_id`** `string`, format: `uuid` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "analysis_data": {}, "created_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Save a file analysis - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/analysis` - **Operation ID:** `createMortgageFileAnalysis` - **Tags:** File analysis analysis_data is required and must be a free-form JSON object (otherwise 400). The API does not support updating or deleting an analysis. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`analysis_data` (required)** `object` — The analysis content (free-form JSON) **Example: default** ```json { "analysis_data": { "summary": "Repayment-to-income ratio 31%", "max_monthly_payment": 8200 } } ``` #### Responses ##### Status: 201 The analysis was saved ###### Content-Type: application/json *Schema `MortgageAnalysis` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "analysis_data": {}, "created_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a file analysis - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/analysis/{analysisId}` - **Operation ID:** `getMortgageFileAnalysis` - **Tags:** File analysis Returns a saved analysis of the mortgage file by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `analysisId` required - **In:** `path` The analysis ID `string`, format: `uuid` #### Responses ##### Status: 200 The analysis ###### Content-Type: application/json *Schema `MortgageAnalysis` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "analysis_data": {}, "created_at": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's calculator mixes - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/calculator-mixes` - **Operation ID:** `getMortgageFileCalculatorMixes` - **Tags:** Calculator mixes Returns the mixes saved on the mortgage file, sorted by last update (most recent first). #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `source` - **In:** `query` Filter by mix source `string`, possible values: `"internal", "smartnpv"` ##### `search` - **In:** `query` Partial, case-insensitive search on the name and description. The characters , ( ) % \_ \ " ' are stripped from the term before searching. `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The mortgage file's mixes ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `CalculatorMix` — A mix saved from the calculator (calculator_mixes) - **`created_at`** `string`, format: `date-time` - **`data`** `object` — Loan track breakdown (jsonb) - **`description`** `string | null` - **`id`** `string`, format: `uuid` - **`lead_id`** `string | null`, format: `uuid` - **`mortgage_file_id`** `string | null`, format: `uuid` - **`name`** `string` - **`organization_id`** `string`, format: `uuid` - **`source`** `string`, possible values: `"internal", "smartnpv"` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "name": "", "description": null, "data": {}, "source": "internal", "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a calculator mix - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/calculator-mixes` - **Operation ID:** `createMortgageFileCalculatorMix` - **Tags:** Calculator mixes name is required (non-empty); otherwise returns 400. source: internal (default) or smartnpv; any other value returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body The mix details **Required:** `true` ##### Content-Type: application/json schema: `CreateCalculatorMix` - **`name` (required)** `string` - **`data`** `object` - **`description`** `string` - **`source`** `string`, possible values: `"internal", "smartnpv"`, default: `"internal"` **Example:** ```json { "name": "", "description": "", "data": {}, "source": "internal" } ``` #### Responses ##### Status: 201 The mix was created ###### Content-Type: application/json *Schema `CalculatorMix` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "name": "", "description": null, "data": {}, "source": "internal", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Get a calculator mix - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/calculator-mixes/{mixId}` - **Operation ID:** `getMortgageFileCalculatorMix` - **Tags:** Calculator mixes Returns a mix of the mortgage file by ID. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `mixId` required - **In:** `path` The mix ID `string`, format: `uuid` #### Responses ##### Status: 200 The mix ###### Content-Type: application/json *Schema `CalculatorMix` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "name": "", "description": null, "data": {}, "source": "internal", "created_at": "", "updated_at": "" } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a calculator mix - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/calculator-mixes/{mixId}` - **Operation ID:** `updateMortgageFileCalculatorMix` - **Tags:** Calculator mixes Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. source must be internal or smartnpv; otherwise returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `mixId` required - **In:** `path` The mix ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateCalculatorMix` - **`data`** `object` - **`description`** `string` - **`name`** `string` - **`source`** `string`, possible values: `"internal", "smartnpv"` **Example:** ```json { "name": "", "description": "", "data": {}, "source": "internal" } ``` #### Responses ##### Status: 200 The updated mix ###### Content-Type: application/json *Schema `CalculatorMix` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "name": "", "description": null, "data": {}, "source": "internal", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a calculator mix - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/calculator-mixes/{mixId}` - **Operation ID:** `patchMortgageFileCalculatorMix` - **Tags:** Calculator mixes Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. source must be internal or smartnpv; otherwise returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `mixId` required - **In:** `path` The mix ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateCalculatorMix` is shown above.* **Example:** ```json { "name": "", "description": "", "data": {}, "source": "internal" } ``` #### Responses ##### Status: 200 The updated mix ###### Content-Type: application/json *Schema `CalculatorMix` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "name": "", "description": null, "data": {}, "source": "internal", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's custom fields - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/custom-fields` - **Operation ID:** `getMortgageFileCustomFields` - **Tags:** Custom fields Returns all of the organization's active custom field definitions for mortgage files (ordered by display_order), each with its current value in the mortgage file (value, or null). Not paginated. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Responses ##### Status: 200 The definitions and values ###### Content-Type: application/json - **`count`** `integer` — Number of items in the data array - **`data`** `array` **Items:** schema: `CustomFieldWithValue` — A custom field definition plus its value for the current file - **`display_order`** `integer` - **`entity_type`** `string`, possible values: `"leads", "mortgage_files", "customers", "contacts"` - **`field_label`** `string` - **`field_name`** `string` - **`field_options`** `object | null` - **`field_type`** `string`, possible values: `"text", "number", "email", "tel", "url", "password", "textarea", "rich_text", "checkbox", "radio", "switch", "select", "date", "datetime", "time", "currency", "multi_select"` - **`id`** `string`, format: `uuid` — Field definition ID - **`is_required`** `boolean` - **`organization_id`** `string`, format: `uuid` - **`value`** `string | null` — The field's current value for the file (null if not set) **Example:** ```json { "data": [ { "id": "", "organization_id": "", "entity_type": "leads", "field_name": "", "field_label": "", "field_type": "text", "field_options": null, "is_required": true, "display_order": 1, "value": null } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Set a custom field value - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/custom-fields/{customFieldId}` - **Operation ID:** `upsertMortgageFileCustomField` - **Tags:** Custom fields Creates or updates the field's value in the mortgage file (PUT and PATCH behave identically). field_value is required; otherwise returns 400. A definition that does not exist in the organization returns 404; a definition that is not for mortgage files returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `customFieldId` required - **In:** `path` The field definition ID (the id from GET /custom-fields) `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`field_value` (required)** `string | null` — The value to save; null clears the value **Example: default** ```json { "field_value": "Example Bank" } ``` #### Responses ##### Status: 200 The saved value ###### Content-Type: application/json schema: `CustomFieldValue` — A custom field value (custom_field_values) - **`created_at`** `string`, format: `date-time` - **`custom_field_id`** `string`, format: `uuid` - **`entity_id`** `string`, format: `uuid` - **`field_value`** `string | null` - **`id`** `string`, format: `uuid` - **`organization_id`** `string`, format: `uuid` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "id": "", "organization_id": "", "custom_field_id": "", "entity_id": "", "field_value": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Set a custom field value (PATCH) - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/custom-fields/{customFieldId}` - **Operation ID:** `patchMortgageFileCustomField` - **Tags:** Custom fields Creates or updates the field's value in the mortgage file (PUT and PATCH behave identically). field_value is required; otherwise returns 400. A definition that does not exist in the organization returns 404; a definition that is not for mortgage files returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `customFieldId` required - **In:** `path` The field definition ID (the id from GET /custom-fields) `string`, format: `uuid` #### Request Body **Required:** `true` ##### Content-Type: application/json - **`field_value` (required)** `string | null` — The value to save; null clears the value **Example: default** ```json { "field_value": "Example Bank" } ``` #### Responses ##### Status: 200 The saved value ###### Content-Type: application/json *Schema `CustomFieldValue` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "custom_field_id": "", "entity_id": "", "field_value": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's milestones - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/milestones` - **Operation ID:** `getMortgageFileMilestonesOverview` - **Tags:** Milestones Returns **all** of the mortgage file's milestones as they appear in the app: for each status in the organization's configuration, its milestones (both the organization's milestones and the file's custom milestones, is_custom=true), each with its progress row (progress, or null) and its checklist items. Unlike /milestones/progress, which returns only progress rows that have already been created, this endpoint returns the definitions even for a new mortgage file. Up to 2,000 rows are fetched from each table; summary.truncated=true indicates that the result was truncated. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Responses ##### Status: 200 Combined view ###### Content-Type: application/json schema: `MilestonesOverview` — Combined view of a file's milestones (definitions + progress + checklists) - **`count`** `integer` — Number of statuses in the response - **`data`** `array` — The organization's statuses, each with its list of milestones (system + custom) **Items:** - **`bgColor`** `string | null` - **`is_hidden`** `boolean` - **`is_locked`** `boolean` - **`key`** `string` — Status identifier (setup, pending, etc.) - **`label`** `string | null` - **`milestones`** `array` **Items:** A milestone, either system or custom (is_custom=true), with its linked progress and checklist - **`checklist`** `array` — Checklist items linked to this milestone **Items:** `object` - **`description`** `string | null` - **`id`** `string` - **`is_custom`** `boolean` — true → source: custom_file_milestones; false → source: organization_settings - **`is_required`** `boolean` - **`label`** `string` - **`order`** `integer | null` - **`progress`** `object | null` — Row from mortgage_milestone_progress (null if not created yet) - **`order`** `integer | null` - **`textColor`** `string | null` - **`summary`** `object` - **`hard_cap`** `integer` — Maximum number of rows retrieved from each table (2000) - **`total_checklist_items`** `integer` - **`total_custom`** `integer` - **`total_milestones`** `integer` - **`total_progress_rows`** `integer` - **`truncated`** `boolean` — true if any of the queries exceeded the hard_cap limit and the result was truncated **Example:** ```json { "data": [ { "key": "", "label": null, "bgColor": null, "textColor": null, "is_locked": true, "is_hidden": true, "order": null, "milestones": [ { "id": "", "label": "", "description": null, "order": null, "is_required": true, "is_custom": true, "progress": null, "checklist": [ {} ] } ] } ], "count": 1, "summary": { "total_milestones": 1, "total_custom": 1, "total_progress_rows": 1, "total_checklist_items": 1, "truncated": true, "hard_cap": 1 } } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's document requirements - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/required-documents` - **Operation ID:** `getMortgageFileRequiredDocuments` - **Tags:** Documents Returns **all** of the organization's document requirement definitions (categories and documents), with each document enriched with the status rows already created for it in the mortgage file (per borrower). Unlike /document-statuses, which returns only rows that have already been created, this endpoint returns the definitions even for a mortgage file in which no requirements have been created yet. The definitions are not filtered by their conditions (employment type, loan purpose, etc.); filtering is the consumer's responsibility. Up to 2,000 status rows are fetched; summary.truncated=true indicates that the result was truncated. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Responses ##### Status: 200 Combined view ###### Content-Type: application/json schema: `RequiredDocumentsOverview` — Combined view of required documents (definitions + statuses) - **`data`** `object` - **`categories`** `array` — Document categories defined by the organization **Items:** `object` **Additional properties:** any (true schema) - **`documents`** `array` — Document definitions. Each document is enriched with statuses\[], the client_document_status rows already created for it **Items:** - **`category_name`** `string | null` — Category name, included for convenience - **`categoryId`** `string` - **`conditions`** `array` **Items:** `object` - **`id`** `string` - **`isRequired`** `boolean` - **`name`** `string` - **`requirement`** `string`, possible values: `"per_borrower", "all_borrowers", "per_account_owner"` - **`statuses`** `array` — Rows from client_document_status (one per borrower) for this document. Empty if none have been created yet. **Items:** *Schema `ClientDocumentStatus` is shown above.* **Additional properties:** any (true schema) - **`summary`** `object` - **`hard_cap`** `integer` — Maximum number of rows retrieved from each table (2000) - **`total_categories`** `integer` - **`total_documents`** `integer` - **`total_status_rows`** `integer` - **`truncated`** `boolean` — true if any of the queries exceeded the hard_cap limit and the result was truncated **Example:** ```json { "data": { "categories": [ { "additionalProperty": "anything" } ], "documents": [ { "id": "", "name": "", "categoryId": "", "category_name": null, "isRequired": true, "requirement": "per_borrower", "conditions": [ {} ], "statuses": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "document_type_id": "", "document_type_title": "", "status": "pending", "uploaded_document_id": null, "upload_progress": 0, "notes": {}, "hide_from_client": true, "created_at": "", "updated_at": "" } ], "additionalProperty": "anything" } ] }, "summary": { "total_categories": 1, "total_documents": 1, "total_status_rows": 1, "truncated": true, "hard_cap": 1 } } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List a mortgage file's custom milestones - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/milestones/custom` - **Operation ID:** `getMortgageFileCustomMilestones` - **Tags:** Milestones Returns the milestones added to this mortgage file only, sorted by custom_order. Not paginated. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Responses ##### Status: 200 The custom milestones ###### Content-Type: application/json - **`count`** `integer` — Number of items in the data array - **`data`** `array` **Items:** schema: `CustomFileMilestone` — A custom milestone on a file (custom_file_milestones) - **`bg_color`** `string | null` - **`checklist_items`** `array | null` **Items:** `object` - **`created_at`** `string`, format: `date-time` - **`custom_order`** `integer | null` - **`description`** `string | null` - **`due_date_after_milestone_id`** `string | null` - **`due_date_specific`** `string | null`, format: `date-time` - **`due_date_type`** `string | null` — How the due date is calculated: none, days, hours, specific_date, days_after_milestone, or days_before_required_date - **`due_date_value`** `integer | null` — Number of days or hours, according to due_date_type - **`id`** `string`, format: `uuid` - **`is_required`** `boolean` - **`label`** `string` - **`linked_type`** `string | null` — Source of the milestone's progress: none, client_documents, client_signatures, or checklist - **`mortgage_file_id`** `string`, format: `uuid` - **`organization_id`** `string`, format: `uuid` - **`status_key`** `string` - **`text_color`** `string | null` - **`updated_at`** `string | null`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "label": "", "description": null, "is_required": true, "bg_color": null, "text_color": null, "linked_type": null, "due_date_type": null, "due_date_value": null, "due_date_specific": null, "due_date_after_milestone_id": null, "custom_order": null, "checklist_items": [ {} ], "created_at": "", "updated_at": null } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Create a custom milestone - **Method:** `POST` - **Path:** `/api-service/mortgage-files/{id}/milestones/custom` - **Operation ID:** `createMortgageFileCustomMilestone` - **Tags:** Milestones Adds a milestone to this mortgage file only. Required: status_key (the key of the status the milestone belongs to) and label; otherwise returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` #### Request Body The milestone details **Required:** `true` ##### Content-Type: application/json schema: `CreateCustomFileMilestone` — Data for creating a custom milestone. status_key and label are required. - **`label` (required)** `string` - **`status_key` (required)** `string` — Key of the status the milestone belongs to - **`bg_color`** `string` - **`checklist_items`** `array` **Items:** `object` - **`custom_order`** `integer` - **`description`** `string` - **`due_date_after_milestone_id`** `string` - **`due_date_specific`** `string`, format: `date-time` - **`due_date_type`** `string` — How the due date is calculated: none, days, hours, specific_date, days_after_milestone, or days_before_required_date - **`due_date_value`** `integer` — Number of days or hours, according to due_date_type - **`is_required`** `boolean`, default: `false` - **`linked_type`** `string` — Source of the milestone's progress: none, client_documents, client_signatures, or checklist - **`text_color`** `string` **Example: default** ```json { "status_key": "signing", "label": "Sign insurance documents", "linked_type": "none", "is_required": true } ``` #### Responses ##### Status: 201 The milestone was created ###### Content-Type: application/json *Schema `CustomFileMilestone` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "label": "", "description": null, "is_required": true, "bg_color": null, "text_color": null, "linked_type": null, "due_date_type": null, "due_date_value": null, "due_date_specific": null, "due_date_after_milestone_id": null, "custom_order": null, "checklist_items": [ {} ], "created_at": "", "updated_at": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a custom milestone - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/milestones/custom/{milestoneId}` - **Operation ID:** `updateMortgageFileCustomMilestone` - **Tags:** Milestones Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `milestoneId` required - **In:** `path` The custom milestone ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateCustomFileMilestone` — Partial update of a custom milestone. - **`bg_color`** `string` - **`checklist_items`** `array` **Items:** `object` - **`custom_order`** `integer` - **`description`** `string` - **`due_date_after_milestone_id`** `string` - **`due_date_specific`** `string`, format: `date-time` - **`due_date_type`** `string` — How the due date is calculated: none, days, hours, specific_date, days_after_milestone, or days_before_required_date - **`due_date_value`** `integer` — Number of days or hours, according to due_date_type - **`is_required`** `boolean` - **`label`** `string` - **`linked_type`** `string` — Source of the milestone's progress: none, client_documents, client_signatures, or checklist - **`status_key`** `string` — Key of the status the milestone belongs to - **`text_color`** `string` **Example:** ```json { "status_key": "", "label": "", "description": "", "is_required": true, "bg_color": "", "text_color": "", "linked_type": "", "due_date_type": "", "due_date_value": 1, "due_date_specific": "", "due_date_after_milestone_id": "", "custom_order": 1, "checklist_items": [ {} ] } ``` #### Responses ##### Status: 200 The updated milestone ###### Content-Type: application/json *Schema `CustomFileMilestone` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "label": "", "description": null, "is_required": true, "bg_color": null, "text_color": null, "linked_type": null, "due_date_type": null, "due_date_value": null, "due_date_specific": null, "due_date_after_milestone_id": null, "custom_order": null, "checklist_items": [ {} ], "created_at": "", "updated_at": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a custom milestone - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/milestones/custom/{milestoneId}` - **Operation ID:** `patchMortgageFileCustomMilestone` - **Tags:** Milestones Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `milestoneId` required - **In:** `path` The custom milestone ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateCustomFileMilestone` is shown above.* **Example:** ```json { "status_key": "", "label": "", "description": "", "is_required": true, "bg_color": "", "text_color": "", "linked_type": "", "due_date_type": "", "due_date_value": 1, "due_date_specific": "", "due_date_after_milestone_id": "", "custom_order": 1, "checklist_items": [ {} ] } ``` #### Responses ##### Status: 200 The updated milestone ###### Content-Type: application/json *Schema `CustomFileMilestone` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "label": "", "description": null, "is_required": true, "bg_color": null, "text_color": null, "linked_type": null, "due_date_type": null, "due_date_value": null, "due_date_specific": null, "due_date_after_milestone_id": null, "custom_order": null, "checklist_items": [ {} ], "created_at": "", "updated_at": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List milestone progress - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/milestones/progress` - **Operation ID:** `getMortgageFileMilestoneProgress` - **Tags:** Milestones Returns the progress rows already created in the mortgage file, sorted by custom_order. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `status_key` - **In:** `query` Filter by status key `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The progress rows ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `MilestoneProgress` — Progress on a milestone (mortgage_milestone_progress) - **`carried_to_status_key`** `string | null` — If the progress was carried over to another status, the key of that status - **`completed_at`** `string | null`, format: `date-time` - **`completed_by`** `string | null`, format: `uuid` - **`completion_percentage`** `integer`, minimum: `0`, maximum: `100` - **`created_at`** `string`, format: `date-time` - **`custom_order`** `integer | null` - **`due_date`** `string | null`, format: `date-time` - **`due_date_override`** `string | null`, format: `date-time` - **`id`** `string`, format: `uuid` - **`is_completed`** `boolean` - **`milestone_id`** `string` - **`mortgage_file_id`** `string`, format: `uuid` - **`notes`** `string | null` - **`organization_id`** `string`, format: `uuid` - **`status_key`** `string` - **`updated_at`** `string | null`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "milestone_id": "", "is_completed": true, "completion_percentage": 0, "completed_at": null, "completed_by": null, "due_date": null, "due_date_override": null, "notes": null, "custom_order": null, "carried_to_status_key": null, "created_at": "", "updated_at": null } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update milestone progress - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/milestones/progress/{progressId}` - **Operation ID:** `updateMortgageFileMilestoneProgress` - **Tags:** Milestones Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. Setting is_completed=true sets completed_at and sets completion_percentage=100 (unless another value is sent); is_completed=false clears completed_at. Completing a milestone may set the due_date of charges linked to it. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `progressId` required - **In:** `path` The progress row ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateMilestoneProgress` - **`completion_percentage`** `integer`, minimum: `0`, maximum: `100` - **`custom_order`** `integer` - **`due_date_override`** `string`, format: `date-time` - **`is_completed`** `boolean` - **`notes`** `string` **Example: default** ```json { "is_completed": true } ``` #### Responses ##### Status: 200 The updated progress row ###### Content-Type: application/json *Schema `MilestoneProgress` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "milestone_id": "", "is_completed": true, "completion_percentage": 0, "completed_at": null, "completed_by": null, "due_date": null, "due_date_override": null, "notes": null, "custom_order": null, "carried_to_status_key": null, "created_at": "", "updated_at": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update milestone progress - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/milestones/progress/{progressId}` - **Operation ID:** `patchMortgageFileMilestoneProgress` - **Tags:** Milestones Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. Setting is_completed=true sets completed_at and sets completion_percentage=100 (unless another value is sent); is_completed=false clears completed_at. Completing a milestone may set the due_date of charges linked to it. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `progressId` required - **In:** `path` The progress row ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateMilestoneProgress` is shown above.* **Example: default** ```json { "is_completed": true } ``` #### Responses ##### Status: 200 The updated progress row ###### Content-Type: application/json *Schema `MilestoneProgress` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "milestone_id": "", "is_completed": true, "completion_percentage": 0, "completed_at": null, "completed_by": null, "due_date": null, "due_date_override": null, "notes": null, "custom_order": null, "carried_to_status_key": null, "created_at": "", "updated_at": null } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### List milestone checklist items - **Method:** `GET` - **Path:** `/api-service/mortgage-files/{id}/milestones/checklist` - **Operation ID:** `getMortgageFileMilestoneChecklist` - **Tags:** Milestones Returns the checklist items of the mortgage file's milestones, sorted by sort_order. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `milestone_id` - **In:** `query` Filter by milestone ID `string` ##### `limit` - **In:** `query` Maximum number of results per page. Defaults to 50, maximum 500 (higher values are capped at 500). An invalid value (non-numeric, zero, or negative) is silently replaced with the default. `integer`, default: `50`, minimum: `1`, maximum: `500` ##### `offset` - **In:** `query` Number of results to skip (for pagination). Defaults to 0, maximum 1,000,000. An invalid value is replaced with 0. `integer`, default: `0`, minimum: `0`, maximum: `1000000` #### Responses ##### Status: 200 The checklist items ###### Content-Type: application/json - **`count`** `integer` — Total number of records matching the filter (not just those on the current page) - **`data`** `array` **Items:** schema: `MilestoneChecklistItem` — A checklist item on a milestone - **`completed_at`** `string | null`, format: `date-time` - **`completed_by`** `string | null`, format: `uuid` - **`created_at`** `string`, format: `date-time` - **`id`** `string`, format: `uuid` - **`is_completed`** `boolean` - **`label`** `string` - **`milestone_id`** `string` - **`mortgage_file_id`** `string`, format: `uuid` - **`organization_id`** `string`, format: `uuid` - **`sort_order`** `integer` - **`status_key`** `string | null` - **`template_item_id`** `string | null` - **`updated_at`** `string`, format: `date-time` **Example:** ```json { "data": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "milestone_id": "", "status_key": null, "template_item_id": null, "label": "", "sort_order": 1, "is_completed": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "" } ], "count": 1 } ``` ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Update a checklist item - **Method:** `PUT` - **Path:** `/api-service/mortgage-files/{id}/milestones/checklist/{itemId}` - **Operation ID:** `updateMortgageFileMilestoneChecklistItem` - **Tags:** Milestones Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. You can update label, sort_order, and is_completed. Setting is_completed=true sets completed_at; false clears it. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `itemId` required - **In:** `path` The checklist item ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json schema: `UpdateMilestoneChecklistItem` - **`is_completed`** `boolean` - **`label`** `string` - **`sort_order`** `integer` **Example: default** ```json { "is_completed": true } ``` #### Responses ##### Status: 200 The updated item ###### Content-Type: application/json *Schema `MilestoneChecklistItem` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "milestone_id": "", "status_key": null, "template_item_id": null, "label": "", "sort_order": 1, "is_completed": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ### Partially update a checklist item - **Method:** `PATCH` - **Path:** `/api-service/mortgage-files/{id}/milestones/checklist/{itemId}` - **Operation ID:** `patchMortgageFileMilestoneChecklistItem` - **Tags:** Milestones Partial update: only the fields you send are updated (PUT and PATCH behave identically). If no updatable field is sent, returns 400. You can update label, sort_order, and is_completed. Setting is_completed=true sets completed_at; false clears it. #### Effective servers - `https://app.banta.co.il` Production #### Authentication - **ApiKeyAuth** ``` { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key in the `x-api-key` header (see the Authentication guide)." } ``` API key in the `x-api-key` header (see the Authentication guide). #### Parameters ##### `id` required - **In:** `path` Mortgage file ID `string`, format: `uuid` ##### `itemId` required - **In:** `path` The checklist item ID `string`, format: `uuid` #### Request Body The fields to update **Required:** `true` ##### Content-Type: application/json *Schema `UpdateMilestoneChecklistItem` is shown above.* **Example: default** ```json { "is_completed": true } ``` #### Responses ##### Status: 200 The updated item ###### Content-Type: application/json *Schema `MilestoneChecklistItem` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "milestone_id": "", "status_key": null, "template_item_id": null, "label": "", "sort_order": 1, "is_completed": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Invalid request: the request body is not valid JSON or is not an object, a required field is missing or empty, a value is invalid, or an update includes no updatable fields ("No updatable fields provided"). The specific cases are listed in each operation's description. Database validation errors are also returned as 400 with a code field: 22P02 (a value in an invalid format, such as an unknown enum value or a malformed UUID), 23514 (a value that is not allowed, such as a status that is not defined in the organization) or 23503 (a reference to a record that does not exist). ##### Status: 401 The API key is missing or invalid. The reason field indicates why: missing_api_key (no x-api-key header was sent), malformed_api_key (the key contains whitespace), invalid_api_key (the key does not exist, has been revoked, or has expired), auth_service_error (an error in the authentication service; you can retry). ##### Status: 403 The key does not have permission for this action on the resource (resource:action), for example write on leads. See the ApiKeyAuth security scheme. ##### Status: 404 The record was not found in the key's organization, or it has been deleted. For paths under /mortgage-files/{id}/..., 404 is also returned when the mortgage file itself is not found. ##### Status: 429 Rate limit exceeded: 60 requests per API key in a fixed 60-second window. The window opens with the first request and resets 60 seconds later, and every request with a valid key counts, including rejected requests. retry_after indicates when the window resets. ##### Status: 500 Server or database error. When it is safe to expose, the code field contains the PostgREST/Postgres error code, for example 23502 (a missing value in a required field). Errors caused by invalid input (22P02, 23503, 23514) are returned as 400, and a duplicate value (23505) as 409. ## Schemas ### Borrower - **Type:** `object` A borrower on a mortgage file: the record that links a customer to the file (relationship type, order, borrower type), together with the linked customer's details. Customer details (name, identification, contact details, etc.) are stored on the customer record and shared across all files in which that customer is a borrower. *Schema `Borrower` is shown above.* **Example:** ```json { "id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "spouse_of_borrower_id": "", "customer_id": "", "order_index": 1, "mortgage_file_id": "", "organization_id": "", "created_at": "", "updated_at": "" } ``` ### Lead - **Type:** `object` A lead: an inquiry from a prospective customer. The response may include additional columns that are not documented here. *Schema `Lead` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "lead_number": "", "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "new", "status_custom": null, "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null, "team_id": "", "borrowers_data": [ { "first_name": "", "last_name": "", "id_number": "", "phone": "", "email": "", "birth_date": "", "relationship_type": "main", "marital_status": "single", "employment_type": "", "monthly_income": 1 } ], "mortgage_request_data": { "property_type": "", "property_value": 1, "property_location": "", "loan_purpose": "" }, "financial_data": { "monthly_income": 1, "existing_obligations": 1, "savings": 1 }, "additional_details": { "additionalProperty": "anything" }, "custom_fields_leads": { "additionalProperty": "anything" }, "converted_to_customer": "", "converted_to_mortgage_file_id": "", "utm_source": "", "utm_medium": "", "utm_campaign": "", "utm_term": "", "utm_content": "", "referrer_url": "", "landing_path": "", "status_changed_at": "", "first_response_time": "", "created_at": "", "updated_at": "", "created_by": "" } ``` ### LeadBorrower - **Type:** `object` Details of a prospective borrower on a lead *Schema `LeadBorrower` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "id_number": "", "phone": "", "email": "", "birth_date": "", "relationship_type": "main", "marital_status": "single", "employment_type": "", "monthly_income": 1 } ``` ### CreateLead - **Type:** `object` Data for creating a lead. Fields not listed here are ignored. *Schema `CreateLead` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "email": "", "phone": "", "source": "api", "status": "new", "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": false, "assigned_to": "" } ``` ### MortgagePurpose - **Type:** `object` A mortgage purpose (purchase, refinance, renovation, etc.) *Schema `MortgagePurpose` is shown above.* **Example:** ```json { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ``` ### MortgageFile - **Type:** `object` A mortgage file (the file record). The response may include additional internal columns that are not documented here. *Schema `MortgageFile` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "" } ``` ### FinancingEntity - **Type:** `object` Financing entity details (bank) *Schema `FinancingEntity` is shown above.* **Example:** ```json { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" } ``` ### MortgageAdditionalInfo - **Type:** `object` Additional information about a mortgage file *Schema `MortgageAdditionalInfo` is shown above.* **Example:** ```json { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } } ``` ### AdditionalExpense - **Type:** `object` An additional expense associated with the transaction *Schema `AdditionalExpense` is shown above.* **Example:** ```json { "type": "", "amount": 1, "description": "" } ``` ### BorrowerIncome - **Type:** `object` A borrower's income data *Schema `BorrowerIncome` is shown above.* **Example:** ```json { "borrowerId": "", "borrowerName": "", "employments": [ { "type": "salaried", "data": { "employers": [ { "company_name": "", "position": "", "start_date": "", "is_current": true, "end_date": "", "salary_slips": [ { "date": "", "amount": "" } ] } ], "is_public_sector": true, "is_controlling_employee": true, "business_name": "", "business_type": "", "years_active": 1, "average_monthly_income": "", "monthly_amount": "", "source": "", "scholarship_amount": "", "institution": "", "description": "", "amount": "" } } ] } ``` ### EmploymentItem - **Type:** `object` An employment/income item *Schema `EmploymentItem` is shown above.* **Example:** ```json { "type": "salaried", "data": { "employers": [ { "company_name": "", "position": "", "start_date": "", "is_current": true, "end_date": "", "salary_slips": [ { "date": "", "amount": "" } ] } ], "is_public_sector": true, "is_controlling_employee": true, "business_name": "", "business_type": "", "years_active": 1, "average_monthly_income": "", "monthly_amount": "", "source": "", "scholarship_amount": "", "institution": "", "description": "", "amount": "" } } ``` ### Incomes - **Type:** `object` Income data for a mortgage file *Schema `Incomes` is shown above.* **Example:** ```json { "borrowers": [ { "borrowerId": "", "borrowerName": "", "employments": [ { "type": "salaried", "data": { "employers": [ { "company_name": "", "position": "", "start_date": "", "is_current": true, "end_date": "", "salary_slips": [ { "date": "", "amount": "" } ] } ], "is_public_sector": true, "is_controlling_employee": true, "business_name": "", "business_type": "", "years_active": 1, "average_monthly_income": "", "monthly_amount": "", "source": "", "scholarship_amount": "", "institution": "", "description": "", "amount": "" } } ] } ] } ``` ### BankAccount - **Type:** `object` A bank account *Schema `BankAccount` is shown above.* **Example:** ```json { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "", "borrowers": [ "" ], "isJoint": true } ``` ### Obligation - **Type:** `object` A financial obligation *Schema `Obligation` is shown above.* **Example:** ```json { "id": "", "type": "bank_loan", "customType": "", "monthlyPayment": 1, "remainingAmount": 1, "endDate": "", "bank_id": "", "bankData": { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "" }, "assignedBorrowers": [ "" ] } ``` ### CreateMortgageFile - **Type:** `object` Data for creating a mortgage file. No fields are required. Fields not listed here are ignored. *Schema `CreateMortgageFile` is shown above.* **Example:** ```json { "file_number": "", "title": "", "status": "new", "status_comment": "", "customer_id": "", "assigned_to": "", "borrowers": [ { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "order_index": 1, "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "customer_id": "" } ], "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "lead_id": "", "source_lead_id": "", "source_lead_number": "", "incomes": { "borrowers": [ { "borrowerId": "", "borrowerName": "", "employments": [ { "type": "salaried", "data": { "employers": [ { "company_name": "", "position": "", "start_date": "", "is_current": true, "end_date": "", "salary_slips": [ {} ] } ], "is_public_sector": true, "is_controlling_employee": true, "business_name": "", "business_type": "", "years_active": 1, "average_monthly_income": "", "monthly_amount": "", "source": "", "scholarship_amount": "", "institution": "", "description": "", "amount": "" } } ] } ] }, "bank_accounts": [ { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "", "borrowers": [ "" ], "isJoint": true } ], "obligations": [ { "id": "", "type": "bank_loan", "customType": "", "monthlyPayment": 1, "remainingAmount": 1, "endDate": "", "bank_id": "", "bankData": { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "" }, "assignedBorrowers": [ "" ] } ] } ``` ### CreateBorrower - **Type:** `object` Data for adding a borrower to a file. Customer fields (name, identification, contact details, etc.) are saved to the customer record, and only when id_number is sent - see the description of the POST /mortgage-files/{id}/borrowers operation. *Schema `CreateBorrower` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "order_index": 1, "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "preferred_contact_methods": [ "email" ], "customer_id": "" } ``` ### UpdateMortgageStatus - **Type:** `object` *Schema `UpdateMortgageStatus` is shown above.* **Example:** ```json { "status": "", "notes": "" } ``` ### Customer - **Type:** `object` A customer in the organization. The response may include additional columns that are not documented here. *Schema `Customer` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "created_at": "", "updated_at": "", "mortgage_files": [ { "id": "", "organization_id": "", "file_number": "", "title": "", "status": "", "status_comment": "", "status_changed_at": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "source_lead_id": "", "source_lead_number": "", "lead_id": "", "drive_folder_url": "", "created_at": "", "updated_at": "", "created_by": "" } ] } ``` ### CreateCustomer - **Type:** `object` Data for creating a customer. Fields not listed here are ignored. *Schema `CreateCustomer` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true } ``` ### ErrorResponse - **Type:** `object` A consistent structure for all error responses. In addition to the fixed error and status fields, some errors add context fields - for example validation, existing_customer_id, related_files_count, related_mortgages_count, existing_link_id, existing_id, provided_type, or available_lists. *Schema `ErrorResponse` is shown above.* **Example:** ```json { "error": "", "details": "", "status": 1, "reason": "missing_api_key", "retry_after": "", "code": "", "validation": { "additionalProperty": "" }, "additionalProperty": "anything" } ``` ### TimelineEvent - **Type:** `object` A timeline event (file created, status changed, etc.) *Schema `TimelineEvent` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "event_type": "", "title": "", "description": null, "metadata": {}, "created_by": null, "created_at": "" } ``` ### Task - **Type:** `object` A task. It can be linked to a mortgage file, a lead, or a customer, or be standalone (all \*\_id fields can be null). The response includes an object for the linked entity (`mortgage_file`/`lead`/`customer`) when one exists. *Schema `Task` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "customer_id": null, "title": "", "description": null, "status": "open", "priority": "low", "due_date": null, "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "", "mortgage_file": { "id": "", "file_number": null, "title": null, "status": null }, "lead": { "id": "", "first_name": null, "last_name": null, "phone": null, "status": null }, "customer": { "id": "", "first_name": null, "last_name": null, "id_number": null } } ``` ### CreateTask - **Type:** `object` Data for creating a task. You can link the task to a file, a lead, and/or a customer, or leave all three IDs empty to create a standalone task. Fields not listed here are ignored. *Schema `CreateTask` is shown above.* **Example:** ```json { "title": "", "description": "", "due_date": "", "status": "open", "priority": "medium", "assigned_to": "", "parent_task_id": "", "progress": 0, "is_favorite": true, "mortgage_file_id": null, "lead_id": null, "customer_id": null } ``` ### UpdateTask - **Type:** `object` A partial update of a task: only the fields that are sent are updated. Replacing or unlinking (null) the linked entity is supported only via PUT/PATCH /tasks/{taskId}; on the /mortgage-files/{id}/tasks/{taskId} path, these fields are ignored. *Schema `UpdateTask` is shown above.* **Example:** ```json { "title": "", "description": "", "due_date": null, "status": "open", "priority": "low", "assigned_to": null, "parent_task_id": null, "progress": 0, "is_favorite": true, "mortgage_file_id": null, "lead_id": null, "customer_id": null } ``` ### Note - **Type:** `object` A note on a mortgage file (entity_notes) *Schema `Note` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": null, "content": "", "is_pinned": true, "is_locked": true, "is_completed": true, "completed_at": null, "created_at": "", "updated_at": null } ``` ### CreateNote - **Type:** `object` Data for creating a note. content is required. *Schema `CreateNote` is shown above.* **Example:** ```json { "content": "", "title": "", "is_pinned": false, "is_locked": false, "is_completed": false } ``` ### UpdateNote - **Type:** `object` *Schema `UpdateNote` is shown above.* **Example:** ```json { "title": "", "content": "", "is_pinned": true, "is_locked": true, "is_completed": true } ``` ### MortgageContactLink - **Type:** `object` A link between a contact and a file (mortgage_contacts) *Schema `MortgageContactLink` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "contact_id": "", "notes": null, "contact": { "id": "", "first_name": "", "last_name": "", "type": "", "custom_type": null, "email": null, "phone": null, "company": null, "job_title": null }, "created_at": "", "updated_at": "" } ``` ### Watcher - **Type:** `object` A user who watches a file (mortgage_file_watchers). Note: `email` is not available through the external API (the email address is stored in auth.users, separately from profiles). *Schema `Watcher` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "watcher_id": "", "watcher": { "id": "", "first_name": "", "last_name": "" }, "created_at": "" } ``` ### ClientDocument - **Type:** `object` A customer document (metadata only; the content is stored in Supabase Storage) *Schema `ClientDocument` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "original_name": "", "stored_name": "", "file_path": "", "file_size": null, "file_type": null, "category": null, "needs_signature": true, "uploaded_by_type": "borrower", "uploaded_by_id": null, "drive_folder_id": null, "drive_file_id": null, "created_at": "" } ``` ### DocumentSignature - **Type:** `object` A signature on a document *Schema `DocumentSignature` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "document_id": "", "borrower_id": "", "is_signed": true, "signed_at": null, "signature_date": null, "document": { "id": "", "original_name": "", "mortgage_file_id": "", "borrower_id": null, "file_path": "" }, "created_at": "" } ``` ### GeneratedDocument - **Type:** `object` A document generated from a template (generated_documents) *Schema `GeneratedDocument` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "template_id": null, "entity_type": "mortgage_file", "entity_id": "", "document_name": "", "filled_content": null, "filled_variables": {}, "signatures": [ {} ], "pdf_path": null, "status": "", "created_at": "", "updated_at": "" } ``` ### ClientDocumentStatus - **Type:** `object` Status of a required document, per borrower *Schema `ClientDocumentStatus` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "document_type_id": "", "document_type_title": "", "status": "pending", "uploaded_document_id": null, "upload_progress": 0, "notes": {}, "hide_from_client": true, "created_at": "", "updated_at": "" } ``` ### Reminder - **Type:** `object` A reminder on a file (reminders) *Schema `Reminder` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "mortgage_file", "entity_id": "", "title": "", "description": null, "remind_at": "", "channels": [ "notification", "email" ], "metadata": {}, "recipient_user_id": null, "is_sent": true, "sent_at": null, "is_dismissed": true, "dismissed_at": null, "created_at": "", "updated_at": "" } ``` ### CreateReminder - **Type:** `object` *Schema `CreateReminder` is shown above.* **Example:** ```json { "title": "", "description": "", "remind_at": "", "channels": [ "" ], "metadata": {}, "recipient_user_id": "" } ``` ### UpdateReminder - **Type:** `object` *Schema `UpdateReminder` is shown above.* **Example:** ```json { "title": "", "description": "", "remind_at": "", "channels": [ "" ], "metadata": {}, "recipient_user_id": "", "is_dismissed": true } ``` ### MortgageCharge - **Type:** `object` A charge (payment request) on a file. The response may include additional payment-processing integration columns that are not documented here. *Schema `MortgageCharge` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "item_name": "", "description": null, "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": null, "due_date_source": "manual", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1, "status": "pending", "notes": null, "external_document_id": null, "external_document_number": null, "external_document_type": null, "external_document_url": null, "external_provider": null, "document_is_cancelled": true, "created_at": "", "updated_at": "" } ``` ### CreateMortgageCharge - **Type:** `object` Data for creating a charge. milestone_id and milestone_status_key must be sent together or not at all; otherwise the request returns 400. *Schema `CreateMortgageCharge` is shown above.* **Example:** ```json { "item_name": "", "description": "", "amount": 0, "includes_vat": true, "is_ancillary_charge": false, "due_date": "", "status": "pending", "notes": "", "milestone_id": "", "milestone_status_key": "", "milestone_due_offset_days": 0 } ``` ### UpdateMortgageCharge - **Type:** `object` Partial update of a charge. The milestone-link pairing rule is evaluated against the merged result (the stored values combined with the request); otherwise the request returns 400. *Schema `UpdateMortgageCharge` is shown above.* **Example:** ```json { "item_name": "", "description": "", "amount": 1, "includes_vat": true, "is_ancillary_charge": true, "due_date": "", "status": "pending", "notes": "", "milestone_id": null, "milestone_status_key": null, "milestone_due_offset_days": 1 } ``` ### MortgagePayment - **Type:** `object` A payment received (mortgage_payments) *Schema `MortgagePayment` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "charge_id": null, "amount": 1, "payment_date": "", "payment_source": "", "payment_method": null, "reference_number": null, "receipt_number": null, "notes": null, "is_cancelled": true, "cancelled_at": null, "external_document_id": null, "external_document_number": null, "external_document_url": null, "created_at": "", "updated_at": "" } ``` ### CreateMortgagePayment - **Type:** `object` *Schema `CreateMortgagePayment` is shown above.* **Example:** ```json { "charge_id": "", "amount": 1, "payment_date": "", "payment_source": "", "payment_method": "", "reference_number": "", "receipt_number": "", "notes": "" } ``` ### UpdateMortgagePayment - **Type:** `object` *Schema `UpdateMortgagePayment` is shown above.* **Example:** ```json { "charge_id": "", "amount": 1, "payment_date": "", "payment_source": "", "payment_method": "", "reference_number": "", "receipt_number": "", "notes": "" } ``` ### MortgageAnalysis - **Type:** `object` A saved file analysis (mortgage_analysis) *Schema `MortgageAnalysis` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "analysis_data": {}, "created_at": "" } ``` ### CalculatorMix - **Type:** `object` A mix saved from the calculator (calculator_mixes) *Schema `CalculatorMix` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": null, "lead_id": null, "name": "", "description": null, "data": {}, "source": "internal", "created_at": "", "updated_at": "" } ``` ### CreateCalculatorMix - **Type:** `object` *Schema `CreateCalculatorMix` is shown above.* **Example:** ```json { "name": "", "description": "", "data": {}, "source": "internal" } ``` ### UpdateCalculatorMix - **Type:** `object` *Schema `UpdateCalculatorMix` is shown above.* **Example:** ```json { "name": "", "description": "", "data": {}, "source": "internal" } ``` ### CustomFieldWithValue - **Type:** `object` A custom field definition plus its value for the current file *Schema `CustomFieldWithValue` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "entity_type": "leads", "field_name": "", "field_label": "", "field_type": "text", "field_options": null, "is_required": true, "display_order": 1, "value": null } ``` ### CustomFieldValue - **Type:** `object` A custom field value (custom_field_values) *Schema `CustomFieldValue` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "custom_field_id": "", "entity_id": "", "field_value": null, "created_at": "", "updated_at": "" } ``` ### CustomFileMilestone - **Type:** `object` A custom milestone on a file (custom_file_milestones) *Schema `CustomFileMilestone` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "label": "", "description": null, "is_required": true, "bg_color": null, "text_color": null, "linked_type": null, "due_date_type": null, "due_date_value": null, "due_date_specific": null, "due_date_after_milestone_id": null, "custom_order": null, "checklist_items": [ {} ], "created_at": "", "updated_at": null } ``` ### CreateCustomFileMilestone - **Type:** `object` Data for creating a custom milestone. status_key and label are required. *Schema `CreateCustomFileMilestone` is shown above.* **Example:** ```json { "status_key": "", "label": "", "description": "", "is_required": false, "bg_color": "", "text_color": "", "linked_type": "", "due_date_type": "", "due_date_value": 1, "due_date_specific": "", "due_date_after_milestone_id": "", "custom_order": 1, "checklist_items": [ {} ] } ``` ### UpdateCustomFileMilestone - **Type:** `object` Partial update of a custom milestone. *Schema `UpdateCustomFileMilestone` is shown above.* **Example:** ```json { "status_key": "", "label": "", "description": "", "is_required": true, "bg_color": "", "text_color": "", "linked_type": "", "due_date_type": "", "due_date_value": 1, "due_date_specific": "", "due_date_after_milestone_id": "", "custom_order": 1, "checklist_items": [ {} ] } ``` ### MilestoneProgress - **Type:** `object` Progress on a milestone (mortgage_milestone_progress) *Schema `MilestoneProgress` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "status_key": "", "milestone_id": "", "is_completed": true, "completion_percentage": 0, "completed_at": null, "completed_by": null, "due_date": null, "due_date_override": null, "notes": null, "custom_order": null, "carried_to_status_key": null, "created_at": "", "updated_at": null } ``` ### UpdateMilestoneProgress - **Type:** `object` *Schema `UpdateMilestoneProgress` is shown above.* **Example:** ```json { "is_completed": true, "completion_percentage": 0, "due_date_override": "", "notes": "", "custom_order": 1 } ``` ### MilestoneChecklistItem - **Type:** `object` A checklist item on a milestone *Schema `MilestoneChecklistItem` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "milestone_id": "", "status_key": null, "template_item_id": null, "label": "", "sort_order": 1, "is_completed": true, "completed_at": null, "completed_by": null, "created_at": "", "updated_at": "" } ``` ### UpdateMilestoneChecklistItem - **Type:** `object` *Schema `UpdateMilestoneChecklistItem` is shown above.* **Example:** ```json { "label": "", "sort_order": 1, "is_completed": true } ``` ### MilestonesOverview - **Type:** `object` Combined view of a file's milestones (definitions + progress + checklists) *Schema `MilestonesOverview` is shown above.* **Example:** ```json { "data": [ { "key": "", "label": null, "bgColor": null, "textColor": null, "is_locked": true, "is_hidden": true, "order": null, "milestones": [ { "id": "", "label": "", "description": null, "order": null, "is_required": true, "is_custom": true, "progress": null, "checklist": [ {} ] } ] } ], "count": 1, "summary": { "total_milestones": 1, "total_custom": 1, "total_progress_rows": 1, "total_checklist_items": 1, "truncated": true, "hard_cap": 1 } } ``` ### RequiredDocumentsOverview - **Type:** `object` Combined view of required documents (definitions + statuses) *Schema `RequiredDocumentsOverview` is shown above.* **Example:** ```json { "data": { "categories": [ { "additionalProperty": "anything" } ], "documents": [ { "id": "", "name": "", "categoryId": "", "category_name": null, "isRequired": true, "requirement": "per_borrower", "conditions": [ {} ], "statuses": [ { "id": "", "organization_id": "", "mortgage_file_id": "", "borrower_id": null, "document_type_id": "", "document_type_title": "", "status": "pending", "uploaded_document_id": null, "upload_progress": 0, "notes": {}, "hide_from_client": true, "created_at": "", "updated_at": "" } ], "additionalProperty": "anything" } ] }, "summary": { "total_categories": 1, "total_documents": 1, "total_status_rows": 1, "truncated": true, "hard_cap": 1 } } ``` ### ListItem - **Type:** `object` An item in a basic list *Schema `ListItem` is shown above.* **Example:** ```json { "key": "", "label": "" } ``` ### StatusListItem - **Type:** `object` An item in a status list, with colors *Schema `StatusListItem` is shown above.* **Example:** ```json { "key": "", "label": "", "bgColor": "", "textColor": "" } ``` ### CalendarEventTypeItem - **Type:** `object` A calendar event type *Schema `CalendarEventTypeItem` is shown above.* **Example:** ```json { "code": "", "name": "", "nameEn": "", "color": "", "icon": "", "sortOrder": 1, "showInCalendar": true, "allowSync": true } ``` ### ListResponse - **Type:** `object` Basic list response *Schema `ListResponse` is shown above.* **Example:** ```json { "data": [ { "key": "", "label": "" } ], "count": 1, "list_type": "" } ``` ### StatusListResponse - **Type:** `object` Status list response *Schema `StatusListResponse` is shown above.* **Example:** ```json { "data": [ { "key": "", "label": "", "bgColor": "", "textColor": "" } ], "count": 1, "list_type": "" } ``` ### CalendarEventTypeListResponse - **Type:** `object` Calendar event type list response *Schema `CalendarEventTypeListResponse` is shown above.* **Example:** ```json { "data": [ { "code": "", "name": "", "nameEn": "", "color": "", "icon": "", "sortOrder": 1, "showInCalendar": true, "allowSync": true } ], "count": 1, "list_type": "" } ``` ### LeadStatus - **Type:** `object` A lead status, including the organization's custom statuses *Schema `LeadStatus` is shown above.* **Example:** ```json { "value": "", "label": "", "color": { "bg": "", "text": "" }, "is_default": true } ``` ### MortgageStatus - **Type:** `object` A mortgage file status, including the organization's custom statuses *Schema `MortgageStatus` is shown above.* **Example:** ```json { "key": "", "label": "", "bgColor": "", "textColor": "", "is_system": true, "is_hidden": true, "order": 1 } ``` ### Contact - **Type:** `object` An organization contact (banker, lawyer, appraiser, etc.) *Schema `Contact` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": null, "notes": "", "created_at": "", "updated_at": "" } ``` ### CreateContact - **Type:** `object` Data for creating a contact. first_name, last_name, and type are required. *Schema `CreateContact` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": "", "notes": "" } ``` ### UpdateContact - **Type:** `object` Partial update of a contact (all fields are optional) *Schema `UpdateContact` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "phone": "", "email": "", "company": "", "job_title": "", "type": "banker", "custom_type": "", "notes": "" } ``` ### UpdateLead - **Type:** `object` Partial update of a lead: only the fields sent are updated. Fields not listed here are ignored. *Schema `UpdateLead` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "email": "", "phone": "", "source": "", "status": "", "notes": "", "mortgage_purpose": "", "required_amount": 1, "total_income": 1, "has_property": true, "assigned_to": null } ``` ### MortgageFileDetails - **Type:** A mortgage file together with its active borrowers *Schema `MortgageFileDetails` is shown above.* ### MortgageFileCreateResult - **Type:** File creation response: the file record together with the results of creating the borrowers, incomes, bank accounts, and obligations *Schema `MortgageFileCreateResult` is shown above.* ### MortgageFileUpdateResult - **Type:** File update response: the updated file record (without borrowers) together with the results of saving the incomes, bank accounts, and obligations *Schema `MortgageFileUpdateResult` is shown above.* ### UpdateMortgageFile - **Type:** `object` Partial update of a file: only the fields sent are updated. Borrowers cannot be updated through this endpoint. Fields not listed here are ignored. *Schema `UpdateMortgageFile` is shown above.* **Example:** ```json { "file_number": "", "title": "", "status": "", "status_comment": "", "customer_id": "", "assigned_to": null, "purposes": [ { "type": "", "amount": 1, "details": "", "fields": { "loan_purpose": "", "tax_declaration": "", "property_value": 1, "appraiser_value": 1, "loan_amount": 1, "equity": 1, "eligibility": 1, "contract_date_payment": "", "mortgage_type": "", "existing_mortgage": 1, "requested_mortgage": 1, "monthly_repayment": 1, "equity_amount": 1, "required_date": "" } } ], "loan_purpose": "", "loan_amount": 1, "total_amount": 1, "monthly_payment": 1, "loan_term": 1, "interest_rate": 1, "property_type": "", "property_value": 1, "property_address": "", "appraiser_value": 1, "equity": 1, "eligibility": 1, "remaining_mortgage": 1, "tax_declaration": "", "contract_date_payment": "", "financing_entity": { "bank_name": "", "branch_number": "", "branch_name": "", "contact_name": "", "contact_phone": "", "contact_email": "" }, "notes": "", "additional_info": { "general_notes": "", "important_info": { "payment_day": 1, "equity_sources": "", "has_grace_period": true, "grace_period_months": 1, "credit_report_status": "", "has_financial_issues": true, "financial_issues_details": "", "requested_monthly_payment": 1 } }, "additional_expenses": [ { "type": "", "amount": 1, "description": "" } ], "real_estate_details": { "additionalProperty": "anything" }, "custom_fields_mortgage": { "additionalProperty": "anything" }, "lead_source": "", "lead_id": "", "source_lead_id": "", "source_lead_number": "", "incomes": { "borrowers": [ { "borrowerId": "", "borrowerName": "", "employments": [ { "type": "salaried", "data": { "employers": [ { "company_name": "", "position": "", "start_date": "", "is_current": true, "end_date": "", "salary_slips": [ {} ] } ], "is_public_sector": true, "is_controlling_employee": true, "business_name": "", "business_type": "", "years_active": 1, "average_monthly_income": "", "monthly_amount": "", "source": "", "scholarship_amount": "", "institution": "", "description": "", "amount": "" } } ] } ] }, "bank_accounts": [ { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "", "borrowers": [ "" ], "isJoint": true } ], "obligations": [ { "id": "", "type": "bank_loan", "customType": "", "monthlyPayment": 1, "remainingAmount": 1, "endDate": "", "bank_id": "", "bankData": { "bankName": "", "bankDisplayName": "", "branchName": "", "branchDisplayName": "", "accountNumber": "" }, "assignedBorrowers": [ "" ] } ] } ``` ### UpdateBorrower - **Type:** `object` Partial update of a borrower. Customer fields update the linked customer record (and apply to all of that customer's files); link fields (relationship_type, custom_relationship, borrower_type, preferred_contact_methods, order_index) apply only to the borrower in this file. *Schema `UpdateBorrower` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "email": "", "phone": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true, "relationship_type": "main", "custom_relationship": "", "borrower_type": "regular", "preferred_contact_methods": [ "email" ], "order_index": 1 } ``` ### BorrowerBase - **Type:** `object` A borrower's link record to a file, without customer details *Schema `BorrowerBase` is shown above.* **Example:** ```json { "id": "", "organization_id": "", "mortgage_file_id": "", "customer_id": null, "order_index": 1, "relationship_type": "main", "borrower_type": "regular", "custom_relationship": null, "preferred_contact_methods": [ "" ], "spouse_of_borrower_id": null, "created_at": "", "updated_at": null } ``` ### UpdateCustomer - **Type:** `object` Partial update of a customer: only the fields sent are updated. Fields not listed here are ignored. *Schema `UpdateCustomer` is shown above.* **Example:** ```json { "first_name": "", "last_name": "", "entity_name": "", "id_type": "israeli_id", "id_number": "", "id_country": "", "issue_date": "", "id_expiry_date": "", "phone": "", "email": "", "birth_date": "", "gender": "male", "marital_status": "single", "custom_marital_status": "", "street": "", "city": "", "has_children": true, "children_under_18": 1, "children_birth_dates": [ "" ], "has_foreign_citizenship": true, "foreign_citizenship": "", "is_politically_exposed": true } ``` ### DeleteResult - **Type:** `object` Deletion result *Schema `DeleteResult` is shown above.* **Example:** ```json { "success": true, "message": "" } ```