Pontosítás: a határidő november 15.
" ] } }, "additionalProperties": false, "required": [ "body" ] } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 9876 ] }, "matter_id": { "type": "integer", "description": "The matter (= case_id) the comment belongs to." }, "parent_id": { "type": [ "integer", "null" ], "description": "The top-level comment this replies to; null for a top-level comment. Replies are one level deep." }, "author_user_id": { "type": [ "integer", "null" ], "description": "User id of the author (null for a legacy import)." }, "author_name": { "type": [ "string", "null" ], "description": "Display name of the author, or null." }, "body": { "type": "string", "description": "The comment as stored: rich HTML, already HTMLPurifier-cleaned for comments written through this API." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the comment was posted, ISO 8601 in the office zone." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Optimistic-lock token: pass it to comments.update as expected_updated_at. Not a display time; null for a legacy comment without one." }, "edited": { "type": "boolean", "description": "True when the comment has been edited since it was posted." } }, "additionalProperties": false }, "updated": { "type": "boolean", "const": true } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request: invalid JSON body, wrong host (use the www. host), or an unreadable request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, invalid, revoked or expired, or its user is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`scope_missing`), missing Flowyer module permission (`module_forbidden`), API disabled for the office, licence expired or office archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint, or the record does not exist / is not visible to the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not offered on this path (DELETE and PUT never are; PATCH only where an update is offered).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The record changed since you read it (`record_conflict`: expected_updated_at no longer matches; read it again and retry with the new updated_at).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is too large (`request_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed or unknown field; `details.fields` lists the field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The office is temporarily unavailable (maintenance or setup in progress); `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error, in the same envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/costs": { "get": { "operationId": "costs.list", "tags": [ "Costs" ], "summary": "List costs", "description": "Lists the live costs of matters the user may see, newest first (an invoiced cost is no longer here). Filter by matter, responsible colleague or date range. Amounts are net. Rows flagged excluded: true are out of the summary and rows flagged locked: true are managed by Flowyer.", "x-scope": "costs:read", "x-flowyer-module": "cases:read, summary:read", "parameters": [ { "name": "matter_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "examples": [ 1234 ] }, "description": "Only costs on this matter.", "example": 1234 }, { "name": "responsible_user_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Only costs recorded for this colleague (a user id from colleagues.list)." }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Only costs on or after this date (YYYY-MM-DD)." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Only costs on or before this date (YYYY-MM-DD)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "examples": [ 25 ], "default": 25 }, "description": "Page size, 1-100. Default 25.", "example": 25 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "examples": [ 0 ], "default": 0 }, "description": "Number of records to skip. Use offset + limit of the previous page to get the next one; `pagination.total` is the full count.", "example": 0 } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Cost id." }, "matter_id": { "type": [ "integer", "null" ], "description": "Matter the cost belongs to." }, "date": { "type": [ "string", "null" ], "format": "date" }, "activity": { "type": [ "string", "null" ], "description": "Description of the cost (plain text)." }, "cost": { "type": [ "number", "null" ], "description": "Net cost amount (no VAT)." }, "cost_invoiceable": { "type": [ "number", "null" ], "description": "Net amount to bill on to the client. It counts towards billing only while excluded is false." }, "currency_id": { "type": [ "integer", "null" ], "description": "Currency id (Flowyer currency list)." }, "currency": { "type": [ "string", "null" ], "description": "Currency ISO code, e.g. HUF, EUR." }, "responsible_user_id": { "type": [ "integer", "null" ] }, "responsible": { "type": [ "string", "null" ] }, "excluded": { "type": "boolean", "description": "True when a colleague excluded the cost from the matter summary: it is not billed and is left out of the billable totals." }, "locked": { "type": "boolean", "description": "True when the cost is managed by Flowyer - mirrored from an incoming invoice, or a disbursement surcharge - and cannot be changed through the API (costs.update answers 409 record_locked, details.reason says which)." }, "approved_for_billing": { "type": "boolean", "description": "True when a colleague approved the cost for billing in the matter summary. It stays editable through the API (as in the web), and the approval is NOT re-requested afterwards: say so before changing the amount of an approved cost." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Send this back as expected_updated_at when updating." } }, "additionalProperties": false } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Malformed request: invalid JSON body, wrong host (use the www. host), or an unreadable request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, invalid, revoked or expired, or its user is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`scope_missing`), missing Flowyer module permission (`module_forbidden`), API disabled for the office, licence expired or office archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint, or the record does not exist / is not visible to the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not offered on this path (DELETE and PUT never are; PATCH only where an update is offered).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed or unknown field; `details.fields` lists the field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The office is temporarily unavailable (maintenance or setup in progress); `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error, in the same envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "costs.create", "tags": [ "Costs" ], "summary": "Record cost", "description": "Records a cost (disbursement) on a matter: date, text (`subject`, read back as `activity`), net amount, net amount billed to the client, and currency (default: the office currency). Amounts are net (no VAT). The responsible colleague defaults to the key's user and is notified otherwise.", "x-scope": "costs:create", "x-flowyer-module": "cases:create, summary:read", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "matter_id": { "type": "integer", "minimum": 1, "description": "Matter the cost belongs to (must be visible).", "examples": [ 1234 ] }, "date": { "type": "string", "format": "date", "description": "Date of the cost, YYYY-MM-DD.", "examples": [ "2026-10-30" ] }, "subject": { "type": "string", "maxLength": 1000, "minLength": 2, "pattern": "^[^<>]*$", "description": "Description of the cost; the read side returns it as `activity` and either name is accepted here (one of the two is required). Plain text; \"<\" and \">\" are not allowed.", "examples": [ "Court filing fee" ] }, "activity": { "type": "string", "maxLength": 1000, "minLength": 2, "pattern": "^[^<>]*$", "description": "The same field as `subject`, under the name the read side uses. Send one of the two." }, "cost": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Net cost amount (no VAT), a whole number in the currency's main unit (cents are not stored).", "examples": [ 15000 ] }, "cost_invoiceable": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Net amount to bill on to the client, a whole number (omit if not billed). It counts towards billing only while the cost is not excluded from the summary.", "examples": [ 15000 ] }, "currency_id": { "type": [ "integer", "null" ], "minimum": 1, "description": "Currency id from the Flowyer currency list (not an ISO code). Omit it to use the office currency (GET /me `office.currency_id` / `office.currency`); an unknown id answers 422 with the accepted ids and codes in details.allowed." }, "responsible_user_id": { "type": [ "integer", "null" ], "minimum": 1, "description": "Responsible colleague: a user id from colleagues.list (look a dictated name up there). Default: the user behind the key." }, "idempotency_key": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9_\\-:.]{1,128}$", "description": "Same role as the Idempotency-Key header, for clients that cannot send custom headers. Letters, digits, `_`, `-`, `:` or `.`, at most 128 characters.", "examples": [ "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b" ] } }, "additionalProperties": false, "required": [ "matter_id", "date", "cost" ], "anyOf": [ { "required": [ "subject" ] }, { "required": [ "activity" ] } ] } } } }, "responses": { "200": { "description": "Idempotent replay: this Idempotency-Key (or, without a key, an identical request within 120 seconds) already created the record; it is returned again, nothing new was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Cost id." }, "matter_id": { "type": [ "integer", "null" ], "description": "Matter the cost belongs to." }, "date": { "type": [ "string", "null" ], "format": "date" }, "activity": { "type": [ "string", "null" ], "description": "Description of the cost (plain text)." }, "cost": { "type": [ "number", "null" ], "description": "Net cost amount (no VAT)." }, "cost_invoiceable": { "type": [ "number", "null" ], "description": "Net amount to bill on to the client. It counts towards billing only while excluded is false." }, "currency_id": { "type": [ "integer", "null" ], "description": "Currency id (Flowyer currency list)." }, "currency": { "type": [ "string", "null" ], "description": "Currency ISO code, e.g. HUF, EUR." }, "responsible_user_id": { "type": [ "integer", "null" ] }, "responsible": { "type": [ "string", "null" ] }, "excluded": { "type": "boolean", "description": "True when a colleague excluded the cost from the matter summary: it is not billed and is left out of the billable totals." }, "locked": { "type": "boolean", "description": "True when the cost is managed by Flowyer - mirrored from an incoming invoice, or a disbursement surcharge - and cannot be changed through the API (costs.update answers 409 record_locked, details.reason says which)." }, "approved_for_billing": { "type": "boolean", "description": "True when a colleague approved the cost for billing in the matter summary. It stays editable through the API (as in the web), and the approval is NOT re-requested afterwards: say so before changing the amount of an approved cost." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Send this back as expected_updated_at when updating." } }, "additionalProperties": false }, "created": { "type": "boolean", "const": false }, "idempotent_replay": { "type": "boolean", "const": true } }, "required": [ "data" ] } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Cost id." }, "matter_id": { "type": [ "integer", "null" ], "description": "Matter the cost belongs to." }, "date": { "type": [ "string", "null" ], "format": "date" }, "activity": { "type": [ "string", "null" ], "description": "Description of the cost (plain text)." }, "cost": { "type": [ "number", "null" ], "description": "Net cost amount (no VAT)." }, "cost_invoiceable": { "type": [ "number", "null" ], "description": "Net amount to bill on to the client. It counts towards billing only while excluded is false." }, "currency_id": { "type": [ "integer", "null" ], "description": "Currency id (Flowyer currency list)." }, "currency": { "type": [ "string", "null" ], "description": "Currency ISO code, e.g. HUF, EUR." }, "responsible_user_id": { "type": [ "integer", "null" ] }, "responsible": { "type": [ "string", "null" ] }, "excluded": { "type": "boolean", "description": "True when a colleague excluded the cost from the matter summary: it is not billed and is left out of the billable totals." }, "locked": { "type": "boolean", "description": "True when the cost is managed by Flowyer - mirrored from an incoming invoice, or a disbursement surcharge - and cannot be changed through the API (costs.update answers 409 record_locked, details.reason says which)." }, "approved_for_billing": { "type": "boolean", "description": "True when a colleague approved the cost for billing in the matter summary. It stays editable through the API (as in the web), and the approval is NOT re-requested afterwards: say so before changing the amount of an approved cost." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Send this back as expected_updated_at when updating." } }, "additionalProperties": false }, "created": { "type": "boolean", "const": true } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request: invalid JSON body, wrong host (use the www. host), or an unreadable request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, invalid, revoked or expired, or its user is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`scope_missing`), missing Flowyer module permission (`module_forbidden`), API disabled for the office, licence expired or office archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint, or the record does not exist / is not visible to the user. `replay_not_visible`: this Idempotency-Key (or, without a key, an identical request) already created the record (`details.record_id`), but it has since been deleted or is not visible to the user; nothing new was created, do not create it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not offered on this path (DELETE and PUT never are; PATCH only where an update is offered).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The Idempotency-Key was used for another resource type (`idempotency_key_reused`), or, without a key, an identical request is being processed right now (`duplicate_in_progress`; retry shortly).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is too large (`request_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed or unknown field; `details.fields` lists the field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The office is temporarily unavailable (maintenance or setup in progress); `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error, in the same envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/costs/{id}": { "get": { "operationId": "costs.get", "tags": [ "Costs" ], "summary": "Get cost", "description": "Returns one live cost by id, if its matter is visible to the user. Amounts are net.", "x-scope": "costs:read", "x-flowyer-module": "cases:read, summary:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Cost id." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Cost id." }, "matter_id": { "type": [ "integer", "null" ], "description": "Matter the cost belongs to." }, "date": { "type": [ "string", "null" ], "format": "date" }, "activity": { "type": [ "string", "null" ], "description": "Description of the cost (plain text)." }, "cost": { "type": [ "number", "null" ], "description": "Net cost amount (no VAT)." }, "cost_invoiceable": { "type": [ "number", "null" ], "description": "Net amount to bill on to the client. It counts towards billing only while excluded is false." }, "currency_id": { "type": [ "integer", "null" ], "description": "Currency id (Flowyer currency list)." }, "currency": { "type": [ "string", "null" ], "description": "Currency ISO code, e.g. HUF, EUR." }, "responsible_user_id": { "type": [ "integer", "null" ] }, "responsible": { "type": [ "string", "null" ] }, "excluded": { "type": "boolean", "description": "True when a colleague excluded the cost from the matter summary: it is not billed and is left out of the billable totals." }, "locked": { "type": "boolean", "description": "True when the cost is managed by Flowyer - mirrored from an incoming invoice, or a disbursement surcharge - and cannot be changed through the API (costs.update answers 409 record_locked, details.reason says which)." }, "approved_for_billing": { "type": "boolean", "description": "True when a colleague approved the cost for billing in the matter summary. It stays editable through the API (as in the web), and the approval is NOT re-requested afterwards: say so before changing the amount of an approved cost." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Send this back as expected_updated_at when updating." } }, "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request: invalid JSON body, wrong host (use the www. host), or an unreadable request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, invalid, revoked or expired, or its user is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`scope_missing`), missing Flowyer module permission (`module_forbidden`), API disabled for the office, licence expired or office archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint, or the record does not exist / is not visible to the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not offered on this path (DELETE and PUT never are; PATCH only where an update is offered).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed or unknown field; `details.fields` lists the field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The office is temporarily unavailable (maintenance or setup in progress); `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error, in the same envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "costs.update", "tags": [ "Costs" ], "summary": "Update cost", "description": "Changes a live cost: text (`subject`, read back as `activity`), date, net amounts, currency and the responsible colleague. A cost flagged locked: true cannot be changed (409 record_locked, details.reason). Pass expected_updated_at; a conflicting change answers 409.", "x-scope": "costs:update", "x-flowyer-module": "cases:modify, summary:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Id of the record to modify." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The `updated_at` value from your most recent read of this record (required whenever the record has one). If the record changed since (a colleague edited it), the API answers 409 and you must re-read before retrying. A legacy record whose `updated_at` is null takes null." }, "date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the cost, YYYY-MM-DD. null keeps the current date." }, "subject": { "type": [ "string", "null" ], "minLength": 1, "description": "Description of the cost, the value the read side returns as `activity` (either name is accepted; null under one of them is \"not given\", only two different texts are refused). Plain text, at most 1000 characters as a NEW value; \"<\" and \">\" cannot be introduced either, but a stored text that is longer or contains them may be sent back unchanged. null keeps the current text." }, "activity": { "type": [ "string", "null" ], "minLength": 1, "description": "The same field as `subject`, under the name the read side uses. Send one of the two (null under the other one is fine)." }, "cost": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Net cost amount (no VAT), a whole number in the currency's main unit (cents are not stored). null clears the amount." }, "cost_invoiceable": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Net amount to bill on to the client, a whole number; null clears it. It counts towards billing only while the cost is not excluded from the summary (excluded is false)." }, "currency_id": { "type": [ "integer", "null" ], "minimum": 0, "description": "Currency id from the Flowyer currency list (not an ISO code; the office currency is GET /me `office.currency_id`). An unknown id answers 422 with the accepted ids and codes in details.allowed. null - or the 0 an unset legacy cost reads back as - keeps the current currency." }, "responsible_user_id": { "type": [ "integer", "null" ], "minimum": 0, "description": "New responsible colleague: an active colleague's user id from colleagues.list. Sending the current one - or null / 0, which a cost without a responsible reads back as - changes nothing." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Cost id." }, "matter_id": { "type": [ "integer", "null" ], "description": "Matter the cost belongs to." }, "date": { "type": [ "string", "null" ], "format": "date" }, "activity": { "type": [ "string", "null" ], "description": "Description of the cost (plain text)." }, "cost": { "type": [ "number", "null" ], "description": "Net cost amount (no VAT)." }, "cost_invoiceable": { "type": [ "number", "null" ], "description": "Net amount to bill on to the client. It counts towards billing only while excluded is false." }, "currency_id": { "type": [ "integer", "null" ], "description": "Currency id (Flowyer currency list)." }, "currency": { "type": [ "string", "null" ], "description": "Currency ISO code, e.g. HUF, EUR." }, "responsible_user_id": { "type": [ "integer", "null" ] }, "responsible": { "type": [ "string", "null" ] }, "excluded": { "type": "boolean", "description": "True when a colleague excluded the cost from the matter summary: it is not billed and is left out of the billable totals." }, "locked": { "type": "boolean", "description": "True when the cost is managed by Flowyer - mirrored from an incoming invoice, or a disbursement surcharge - and cannot be changed through the API (costs.update answers 409 record_locked, details.reason says which)." }, "approved_for_billing": { "type": "boolean", "description": "True when a colleague approved the cost for billing in the matter summary. It stays editable through the API (as in the web), and the approval is NOT re-requested afterwards: say so before changing the amount of an approved cost." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Send this back as expected_updated_at when updating." } }, "additionalProperties": false }, "updated": { "type": "boolean", "const": true } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request: invalid JSON body, wrong host (use the www. host), or an unreadable request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, invalid, revoked or expired, or its user is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`scope_missing`), missing Flowyer module permission (`module_forbidden`), API disabled for the office, licence expired or office archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint, or the record does not exist / is not visible to the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not offered on this path (DELETE and PUT never are; PATCH only where an update is offered).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The record changed since you read it (`record_conflict`: expected_updated_at no longer matches; read it again and retry with the new updated_at), or it has been invoiced / locked and can no longer be modified through the API (`record_locked`; make the change in Flowyer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is too large (`request_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed or unknown field; `details.fields` lists the field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The office is temporarily unavailable (maintenance or setup in progress); `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error, in the same envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/courts": { "get": { "operationId": "courts.list", "tags": [ "Courts" ], "summary": "List courts", "description": "Lists the shared court registry (id, name, city) for the court_id of trials.create / trials.update. With `q` (a court name as heard; accents, casing and small typos tolerated) answers status exact/similar/none: only \"exact\" is safe to use directly. It is the Hungarian court directory.", "x-scope": "courts:read", "x-flowyer-module": null, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255, "examples": [ "Fővárosi Törvényszék" ] }, "description": "A court name to look up, as heard or dictated, in any word order. Omit it to list every court.", "example": "Fővárosi Törvényszék" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 }, "description": "Maximum courts to return (default 200)." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": [ "string", "null" ], "enum": [ "exact", "similar", "none", null ], "description": "Only with `q`: exact = one confident match (safe to use its id), similar = approximate or several matches (confirm with the user first), none = no match (ask the user). Null without `q`." }, "courts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Court id: pass it as court_id to trials.create / trials.update." }, "name": { "type": "string", "description": "Court name as shown in Flowyer." }, "city": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "description": "Courts, best match first with `q`, otherwise by name." }, "total": { "type": "integer", "description": "How many courts matched (all courts without `q`) before the list was cut to `limit`." }, "truncated": { "type": "boolean", "description": "True when more courts matched than were returned: narrow `q` or raise `limit`." } }, "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request: invalid JSON body, wrong host (use the www. host), or an unreadable request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, invalid, revoked or expired, or its user is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`scope_missing`), API disabled for the office, licence expired or office archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint, or the record does not exist / is not visible to the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not offered on this path (DELETE and PUT never are; PATCH only where an update is offered).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed or unknown field; `details.fields` lists the field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The office is temporarily unavailable (maintenance or setup in progress); `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error, in the same envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{id}": { "patch": { "operationId": "documents.rename", "tags": [ "Documents" ], "summary": "Rename document", "description": "Renames a document (its display name only; the file content is unchanged). The new name must be unique in the same folder of the matter. Pass expected_updated_at from your last read; a conflicting change answers 409.", "x-scope": "documents:update", "x-flowyer-module": "cases:modify", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Id of the record to modify." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The `updated_at` value from your most recent read of this record (required whenever the record has one). If the record changed since (a colleague edited it), the API answers 409 and you must re-read before retrying. A legacy record whose `updated_at` is null takes null." }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[^<>]*$", "description": "New file name, at most 255 characters INCLUDING the extension. The current extension is kept if you omit one, and it counts towards the 255 (so an extension-less name for \"Beadvany.pdf\" may be at most 251 characters). Plain text; \"<\" and \">\" are not allowed, so a document whose stored name contains one can only be renamed in Flowyer.", "examples": [ "Contract_signed.pdf" ] } }, "additionalProperties": false, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "File name as shown in Flowyer: the name stored with the document, or its storage name when it was imported from an older system without one. documents.list is ordered by the stored name: documents that have one come first, alphabetically, then the imported ones without a stored name, oldest first (the order they were filed in Flowyer), which are therefore not sorted by the name shown here. The order is the same on every page, so limit and offset page through the list without repeats or gaps.", "examples": [ "Contract_v2.docx" ] }, "size": { "type": [ "integer", "null" ], "description": "Bytes." }, "version": { "type": "integer", "description": "Current version number of the file." }, "folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "path": { "type": "string", "description": "Folder path inside the matter, \"/\" separated." } }, "additionalProperties": false, "description": "The folder the document is filed in, or null at the matter root. documents.upload.complete answers null when the folder chosen at documents.upload.init was deleted while the bytes were uploading: the document is then filed at the matter root, which is where Flowyer shows it. If the root already holds a document of that name, the upload is filed under a suffixed name (\"Contract_2.pdf\") instead of becoming a new version of that unrelated document; the 201 echoes the stored `name`." }, "folder_deleted": { "type": "boolean", "description": "True when the document is filed in a folder that no longer exists, which Flowyer's own file list does not show (`folder` is null for it, as it is for a document at the matter root). documents.upload.complete answers true only if the folder was deleted while the bytes were uploading AND moving the stored file to the matter root failed: the document is then kept in the deleted folder, where its contents are still reachable. False for everything else, a normal root filing included." }, "created_by_user_id": { "type": [ "integer", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "updated": { "type": "boolean", "const": true } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request: invalid JSON body, wrong host (use the www. host), or an unreadable request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, invalid, revoked or expired, or its user is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`scope_missing`), missing Flowyer module permission (`module_forbidden`), API disabled for the office, licence expired or office archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint, or the record does not exist / is not visible to the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not offered on this path (DELETE and PUT never are; PATCH only where an update is offered).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The record changed since you read it (`record_conflict`: expected_updated_at no longer matches; read it again and retry with the new updated_at), or another document in the same folder already has this name (`duplicate_name`; choose another name, do not retry the same one).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is too large (`request_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed or unknown field; `details.fields` lists the field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The office is temporarily unavailable (maintenance or setup in progress); `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error, in the same envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{id}/download": { "get": { "operationId": "documents.download", "tags": [ "Documents" ], "summary": "Download document", "description": "Returns a short-lived signed URL to download one document by id, if its matter is visible. GET the url to fetch the bytes; it expires in a few minutes.", "x-scope": "documents:download", "x-flowyer-module": "cases:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Document id (from documents.list)." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "download_url": { "type": "string", "description": "Signed URL. GET it to download the file bytes." }, "filename": { "type": "string", "description": "File name for the download." }, "size": { "type": [ "integer", "null" ], "description": "Bytes." }, "expires_in": { "type": "integer", "description": "Seconds until the URL expires." } }, "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request: invalid JSON body, wrong host (use the www. host), or an unreadable request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, invalid, revoked or expired, or its user is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`scope_missing`), missing Flowyer module permission (`module_forbidden`), API disabled for the office, licence expired or office archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint, or the record does not exist / is not visible to the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not offered on this path (DELETE and PUT never are; PATCH only where an update is offered).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed or unknown field; `details.fields` lists the field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The office is temporarily unavailable (maintenance or setup in progress); `Retry-After` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error, in the same envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails/{id}": { "get": { "operationId": "emails.get", "tags": [ "Emails" ], "summary": "Get email", "description": "Returns one saved email of a matter with its plain-text body (sender, subject, size and who saved it). The raw HTML body is never returned. Answers 404 when the email does not exist or its matter is not visible to the user who owns this API key.", "x-scope": "emails:read", "x-flowyer-module": "emails:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "examples": [ 1234 ] }, "description": "Email id.", "example": 1234 } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1234 ] }, "matter": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "case_number": { "type": "string" } }, "additionalProperties": false, "description": "The matter the mail is filed under, or null for a caseless mail (saved outside any case)." }, "from_name": { "type": [ "string", "null" ], "description": "Display name of the outside party (never a colleague; the store has no direction column)." }, "from_address": { "type": [ "string", "null" ], "description": "SMTP address of the outside party." }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ], "description": "The message body as plain text. The raw HTML body is deliberately never returned (untrusted third-party HTML). Best-effort plain text: if the original HTML carried