{ "openapi": "3.1.0", "info": { "title": "Well Document API", "version": "1.0.0", "description": "API for uploading and managing financial documents in the Well platform" }, "servers": [ { "url": "https://api.wellapp.ai" } ], "paths": { "/v1/api-key": { "post": { "summary": "Create API Key", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "api-key" }, "attributes": { "type": "object", "properties": { "name": { "type": "string" }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "name", "workspace" ], "additionalProperties": false } }, "required": [ "type", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "API Key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/api-key/{id}": { "delete": { "summary": "Delete API Key", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "API Key deleted" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/ApiKeyNotFound" } } } }, "/v1/documents": { "post": { "summary": "Create a document", "description": "Create a new document record with file and metadata", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The document file to upload (PDF, image, Word document, etc.)" }, "data.type": { "type": "string", "const": "document", "description": "Resource type identifier" }, "data.attributes.file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name of the document file" }, "data.attributes.workspace_id": { "type": "string", "format": "uuid", "description": "Workspace UUID" }, "data.attributes.external_workspace_id": { "type": "string", "format": "uuid", "description": "External Workspace UUID" }, "data.attributes.collect_id": { "type": "string", "format": "uuid", "description": "Collection UUID (optional)" }, "data.attributes.metadata.source_number": { "type": "string", "description": "Source phone number for the document" }, "data.attributes.metadata.target_number": { "type": "string", "description": "Target phone number for the document" }, "data.attributes.metadata.document_type": { "type": "string", "enum": [ "invoice", "receipt", "purchase_order", "..." ], "description": "Type of document classification. See [all document types](/enums/universal-document-class-type) for complete list." }, "data.relationships.workspace.data.type": { "type": "string", "const": "workspace", "description": "Type for workspace relationship" }, "data.relationships.workspace.data.id": { "type": "string", "format": "uuid", "description": "UUID of the workspace to associate with this document" }, "data.relationships.company.data.type": { "type": "string", "const": "company", "description": "Type for company relationship" }, "data.relationships.company.data.id": { "type": "string", "format": "uuid", "description": "UUID of the company to associate with this document" }, "data.relationships.people.data.type": { "type": "string", "const": "people", "description": "Type for people relationship" }, "data.relationships.people.data.id": { "type": "string", "format": "uuid", "description": "UUID of the person to associate with this document" }, "data.relationships.people.data.meta.phone_number": { "type": "string", "description": "Phone number to identify the person (alternative to ID)" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Document created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "data": { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "invoice_2024.pdf", "workspace_id": "550e8400-e29b-41d4-a716-446655440001", "collect_id": "550e8400-e29b-41d4-a716-446655440002", "metadata": { "source_number": "+33123456789", "target_number": "+33987654321", "document_type": "invoice" }, "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:30:00Z" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "company": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "people": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440004", "meta": { "phone_number": "+33123456789" } } } } }, "included": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "Sales Team Workspace", "description": "Workspace for sales documents and invoices", "avatar_color": "#4A90E2", "external_workspace_id": "sales_ws_001", "auto_extract_enabled": true, "created_at": "2024-01-15T09:00:00Z", "updated_at": "2024-01-15T09:00:00Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "name": "ACME Corporation", "description": "Leading technology and consulting company", "locale": "fr", "domain_name_primary_link_url": "acme.com", "tax_id": { "value": "FR12345678901", "type": "VAT" }, "registration": { "trade_name": "ACME", "registered_name": "ACME Corporation SAS" }, "registration_number": { "business_type": "SAS", "value": "RCS 123456789", "registry_name": "Registre du Commerce Paris", "registry_country": "FR" }, "created_at": "2024-01-10T08:00:00Z", "updated_at": "2024-01-10T08:00:00Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440004", "attributes": { "first_name": "Jean", "last_name": "Dupont", "full_name": "Jean Dupont", "created_at": "2024-01-12T10:00:00Z", "updated_at": "2024-01-12T10:00:00Z" } } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/CompanyOrPersonNotFound" }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "example": { "code": "PAYLOAD_TOO_LARGE", "status": 413, "title": "Payload Too Large", "message": "The uploaded file exceeds the maximum allowed size", "meta": { "log_id": "550e8400-e29b-41d4-a716-446655440999" } } } } } } }, "get": { "summary": "List documents", "description": "Retrieve a list of documents with optional filtering, sorting, and relationship inclusion. By default, only document IDs are returned for relationships.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "media", "invoice" ] }, "description": "Include detailed relationship data in the response. Comma-separated values supported.", "example": "media,invoice" }, { "name": "filter[uploaded_at][from]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter documents uploaded from this date/time", "example": "2024-01-01T00:00:00Z" }, { "name": "filter[uploaded_at][to]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter documents uploaded up to this date/time", "example": "2024-12-31T23:59:59Z" }, { "name": "filter[processed_at][from]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter documents processed from this date/time", "example": "2024-01-01T00:00:00Z" }, { "name": "filter[processed_at][to]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter documents processed up to this date/time", "example": "2024-12-31T23:59:59Z" }, { "name": "filter[workspace_id]", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter documents by workspace ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "filter[external_workspace_id]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter documents by external workspace ID", "example": "ext-workspace-123" }, { "name": "filter[status]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "deleted" ] }, "description": "Filter documents by processing status", "example": "completed" }, { "name": "filter[file_type]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pdf", "image", "word", "excel", "text" ] }, "description": "Filter documents by file type", "example": "pdf" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "uploaded_at", "-uploaded_at", "processed_at", "-processed_at" ] }, "description": "Sort documents by field. Use - prefix for descending order.", "example": "-uploaded_at" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of documents per page", "example": 20 } ], "responses": { "200": { "description": "Documents retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } }, "example": { "data": [ { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "invoice_2024.pdf", "workspace_id": "550e8400-e29b-41d4-a716-446655440001", "collect_id": "550e8400-e29b-41d4-a716-446655440002", "metadata": { "source_number": "+33123456789", "target_number": "+33987654321", "document_type": "invoice" }, "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:30:00Z" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "company": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "people": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440004", "meta": { "phone_number": "+33123456789" } } } } } ], "included": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "Sales Team Workspace", "description": "Workspace for sales documents and invoices", "avatar_color": "#4A90E2", "external_workspace_id": "sales_ws_001", "auto_extract_enabled": true, "created_at": "2024-01-15T09:00:00Z", "updated_at": "2024-01-15T09:00:00Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "name": "ACME Corporation", "description": "Leading technology and consulting company", "locale": "fr", "domain_name_primary_link_url": "acme.com", "tax_id": { "value": "FR12345678901", "type": "VAT" }, "registration": { "trade_name": "ACME", "registered_name": "ACME Corporation SAS" }, "registration_number": { "business_type": "SAS", "value": "RCS 123456789", "registry_name": "Registre du Commerce Paris", "registry_country": "FR" }, "created_at": "2024-01-10T08:00:00Z", "updated_at": "2024-01-10T08:00:00Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440004", "attributes": { "first_name": "Jean", "last_name": "Dupont", "full_name": "Jean Dupont", "created_at": "2024-01-12T10:00:00Z", "updated_at": "2024-01-12T10:00:00Z" } } ], "meta": { "total": 150, "page": 1, "limit": 20 } } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/documents/{id}": { "get": { "summary": "Get a document", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "data": { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "invoice_2024.pdf", "workspace_id": "550e8400-e29b-41d4-a716-446655440001", "collect_id": "550e8400-e29b-41d4-a716-446655440002", "metadata": { "source_number": "+33123456789", "target_number": "+33987654321", "document_type": "invoice" }, "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:30:00Z" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "company": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "people": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440004", "meta": { "phone_number": "+33123456789" } } } } }, "included": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "Sales Team Workspace", "description": "Workspace for sales documents and invoices", "avatar_color": "#4A90E2", "external_workspace_id": "sales_ws_001", "auto_extract_enabled": true, "created_at": "2024-01-15T09:00:00Z", "updated_at": "2024-01-15T09:00:00Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "name": "ACME Corporation", "description": "Leading technology and consulting company", "locale": "fr", "domain_name_primary_link_url": "acme.com", "tax_id": { "value": "FR12345678901", "type": "VAT" }, "registration": { "trade_name": "ACME", "registered_name": "ACME Corporation SAS" }, "registration_number": { "business_type": "SAS", "value": "RCS 123456789", "registry_name": "Registre du Commerce Paris", "registry_country": "FR" }, "created_at": "2024-01-10T08:00:00Z", "updated_at": "2024-01-10T08:00:00Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440004", "attributes": { "first_name": "Jean", "last_name": "Dupont", "full_name": "Jean Dupont", "created_at": "2024-01-12T10:00:00Z", "updated_at": "2024-01-12T10:00:00Z" } } ] } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/DocumentNotFound" } } }, "delete": { "summary": "Delete a document", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/DocumentNotFound" } } } }, "/v1/subscriptions/webhooks": { "post": { "summary": "Create webhook subscription", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" }, "example": { "type": "webhook", "attributes": { "target_url": "https://webhook.site/d96a94d9-8458-4956-857e-11c85843baa2", "event": "document.processed", "headers": { "secret": "secret" } } } } } }, "responses": { "200": { "description": "Subscription created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" }, "example": { "data": { "type": "webhook", "id": "6843888f-1aa5-440b-afac-b0edca649ad2", "attributes": { "event": "document.processed", "target_url": "https://webhook.site/d96a94d9-8458-4956-857e-11c85843baa2", "headers": { "secret": "secret" }, "created_at": "2025-09-22T08:57:03.662Z", "active": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "get": { "summary": "List webhook subscriptions", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "responses": { "200": { "description": "Subscription created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" }, "example": { "data": [ { "type": "webhook", "id": "6843888f-1aa5-440b-afac-b0edca649ad2", "attributes": { "event": "document.processed", "target_url": "https://webhook.site/d96a94d9-8458-4956-857e-11c85843baa2", "headers": { "secret": "secret" }, "created_at": "2025-09-22T08:57:03.662Z", "active": true } } ] } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/subscriptions/webhooks/{id}": { "get": { "summary": "Retrieve webhook subscription", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscription details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/WebhookNotFound" } } }, "patch": { "summary": "Update webhook subscription", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/WebhookNotFound" } } }, "delete": { "summary": "Delete webhook subscription", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/invoices": { "get": { "summary": "List invoices", "description": "Retrieve a list of invoices filtered by issuer, receiver, status or date range. Supports pagination following JSON:API specification.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "issuer_id", "in": "query", "schema": { "type": "string" }, "description": "Filter invoices where the specified company is the issuer." }, { "name": "receiver_id", "in": "query", "schema": { "type": "string" }, "description": "Filter invoices where the specified company is the receiver." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "sent", "paid", "cancelled" ] }, "description": "Filter invoices by status." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter invoices issued on or after this date (YYYY-MM-DD)." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter invoices issued on or before this date (YYYY-MM-DD)." }, { "name": "page[limit]", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Number of invoices per page." }, { "name": "page[cursor]", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination." }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "company", "payment_means", "people", "document" ] }, "description": "Include related resources in the response. Multiple relationships can be included by separating them with commas." } ], "responses": { "200": { "description": "Invoices retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceResponse" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of invoices" }, "page": { "type": "integer", "description": "Current page number" }, "limit": { "type": "integer", "description": "Number of invoices per page" } } } } }, "example": { "data": [ { "type": "invoice", "id": "invoice_550e8400-e29b-41d4-a716-446655440000", "attributes": { "reference_number": "INV-2025-001", "document_type": "commercial_invoice", "document_type_code": "380", "issue_date": "2025-01-15", "due_date": "2025-02-15", "local_currency": "EUR", "local_totals": { "subtotal": "1000.00", "tax_total": "200.00", "total_amount": "1200.00" }, "terms": "Payment due within 30 days", "billing_context": "subscription", "payment_status": { "paid": true, "amount_paid": 123, "amount_remaining": 123 }, "status": "draft", "description": "Professional services invoice for January 2025", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" }, "relationships": { "issuer": { "data": { "type": "company", "id": "company-issuer-uuid" } }, "receiver": { "data": { "type": "company", "id": "company-receiver-uuid" } }, "payment_means": { "data": [ { "type": "payment_means", "id": "pm_1" } ] }, "invoice_items": { "data": [ { "type": "invoice_item", "id": "item_1" } ] }, "document": { "data": { "type": "document", "id": "doc_original_invoice" } }, "people": { "data": [ { "type": "people", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" } ] } } } ], "included": [ { "type": "people", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "attributes": { "first_name": "John", "last_name": "Smith", "full_name": "John Smith", "email": "jsmith@example.com", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "document", "id": "doc_original_invoice", "attributes": { "file_name": "invoice_2025_001.pdf", "status": "processed", "uploaded_at": "2023-11-07T05:31:56Z", "processed_at": "2023-11-07T05:31:56Z", "file_type": "application/pdf", "size_bytes": 245678, "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "invoice_item", "id": "item_1", "attributes": { "line_id": "1", "sku": "WM-1001", "name": "Wireless Mouse", "description": "Ergonomic wireless mouse with USB receiver", "unit_price": 25, "currency": "EUR", "unit": "EA", "min_quantity": 1, "max_quantity": 500, "tax": { "rate": 20, "category": "standard", "scheme": "VAT" }, "period": { "start": "2025-06-26", "end": "2025-06-27" }, "created_at": "2025-05-11T13:42:12Z", "updated_at": "2025-05-11T13:45:20Z" } }, { "type": "payment_means", "id": "pm_1", "attributes": { "type": "card_details", "scheme": "SEPA", "status": "active", "account_details": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "account_number": "532013000", "routing_number": "37040044", "currency": "EUR" }, "bank_details": { "bank_name": "Commerzbank AG", "bank_code": "37040044", "branch_name": "Main Branch", "branch_code": "440" }, "card_details": { "masked_pan": "****1234", "brand": "visa", "card_type": "credit", "expiry_month": 12, "expiry_year": 2027, "cardholder_name": "John Smith" }, "digital_wallet": { "provider": "paypal", "wallet_id": "john.smith@example.com", "wallet_type": "personal" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared", "sanctions_check": "passed", "last_compliance_check": "2023-11-07T05:31:56Z" }, "metadata": { "source": "api", "external_id": "ext_pm_12345" }, "nickname": "Primary Payment Method", "description": "Main company payment account", "tags": [ "primary", "sepa" ], "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "company", "id": "company-receiver-uuid", "attributes": { "name": "ACME Corporation", "description": "Technology solutions provider", "domain_name_primary_link_url": "acme.com", "locale": "en", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "ACME Corporation GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" }, "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "company", "id": "company-issuer-uuid", "attributes": { "name": "Service Provider Inc", "description": "Professional services company", "domain_name_primary_link_url": "serviceprovider.com", "locale": "en", "tax_id": { "value": "FR987654321", "type": "VAT" }, "registration": { "trade_name": "Service Provider", "registered_name": "Service Provider Inc." }, "registration_number": { "business_type": "Inc", "value": "RCS 987654", "registry_name": "Paris Commercial Registry", "registry_country": "FR" }, "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } } ], "meta": { "total": 150, "page": 1, "limit": 20 } } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "post": { "summary": "Create a new invoice", "description": "Create a new invoice with comprehensive details including issuer/receiver relationships, payment terms, line items, and document attachments. Supports both basic invoice creation and complex scenarios with detailed billing contexts.", "tags": [ "Invoices" ], "operationId": "createInvoice", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePost" }, "examples": { "complete_invoice": { "summary": "Complete invoice with payment and relationships", "description": "Example of creating a comprehensive invoice with all relationships and payment details", "value": { "type": "invoices", "attributes": { "reference_number": "INV-2025-0456", "issue_date": "2025-06-19", "due_date": "2025-07-19", "document_type_code": "380", "local_currency": "EUR", "local_totals": { "items_total": 2500, "tax_total": 500, "grand_total": 3000 }, "terms": "Net 30", "status": "sent", "payment_status": { "paid": true, "local_amount_paid": 3000, "local_amount_remaining": 0 }, "billing_context": "subscription", "description": "Monthly cloud hosting subscription" }, "relationships": { "issuer": { "data": { "type": "company", "id": "company_id" } }, "receiver": { "data": { "type": "company", "id": "company_id_2" } }, "payment_type": { "data": [ { "type": "payment_means", "id": "id1" }, { "type": "payment_means", "id": "id2" } ] }, "invoice_items": { "data": [ { "type": "invoice_item", "id": "id1" }, { "type": "invoice_item", "id": "id2" } ] }, "documents": { "data": { "type": "document", "id": "doc_original_invoice" } } } } } } } } }, "responses": { "201": { "description": "Invoice created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" }, "example": { "data": { "type": "invoice", "id": "invoice_550e8400-e29b-41d4-a716-446655440000", "attributes": { "reference_number": "INV-2025-001", "document_type": "commercial_invoice", "document_type_code": "380", "issue_date": "2025-01-15", "due_date": "2025-02-15", "local_currency": "EUR", "local_totals": { "subtotal": "1000.00", "tax_total": "200.00", "total_amount": "1200.00" }, "terms": "Payment due within 30 days", "billing_context": "subscription", "payment_status": { "paid": true, "amount_paid": 123, "amount_remaining": 123 }, "status": "draft", "description": "Professional services invoice for January 2025", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" }, "relationships": { "issuer": { "data": { "type": "company", "id": "company-issuer-uuid" } }, "receiver": { "data": { "type": "company", "id": "company-receiver-uuid" } }, "payment_means": { "data": [ { "type": "payment_means", "id": "pm_1" } ] }, "invoice_items": { "data": [ { "type": "invoice_item", "id": "item_1" } ] }, "documents": { "data": { "type": "document", "id": "doc_original_invoice" } }, "people": { "data": [ { "type": "people", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" } ] } } }, "included": [ { "type": "people", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "attributes": { "first_name": "John", "last_name": "Smith", "full_name": "John Smith", "email": "jsmith@example.com", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "document", "id": "doc_original_invoice", "attributes": { "file_name": "invoice_2025_001.pdf", "status": "processed", "uploaded_at": "2023-11-07T05:31:56Z", "processed_at": "2023-11-07T05:31:56Z", "file_type": "application/pdf", "size_bytes": 245678, "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "invoice_item", "id": "item_1", "attributes": { "line_id": "1", "sku": "WM-1001", "name": "Wireless Mouse", "description": "Ergonomic wireless mouse with USB receiver", "unit_price": 25, "currency": "EUR", "unit": "EA", "min_quantity": 1, "max_quantity": 500, "tax": { "rate": 20, "category": "standard", "scheme": "VAT" }, "period": { "start": "2025-06-26", "end": "2025-06-27" }, "created_at": "2025-05-11T13:42:12Z", "updated_at": "2025-05-11T13:45:20Z" } }, { "type": "payment_means", "id": "pm_1", "attributes": { "type": "card_details", "scheme": "SEPA", "status": "active", "account_details": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "account_number": "532013000", "routing_number": "37040044", "currency": "EUR" }, "bank_details": { "bank_name": "Commerzbank AG", "bank_code": "37040044", "branch_name": "Main Branch", "branch_code": "440" }, "card_details": { "masked_pan": "****1234", "brand": "visa", "card_type": "credit", "expiry_month": 12, "expiry_year": 2027, "cardholder_name": "John Smith" }, "digital_wallet": { "provider": "paypal", "wallet_id": "john.smith@example.com", "wallet_type": "personal" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared", "sanctions_check": "passed", "last_compliance_check": "2023-11-07T05:31:56Z" }, "metadata": { "source": "api", "external_id": "ext_pm_12345" }, "nickname": "Primary Payment Method", "description": "Main company payment account", "tags": [ "primary", "sepa" ], "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "company", "id": "company-receiver-uuid", "attributes": { "name": "ACME Corporation", "description": "Technology solutions provider", "domain_name_primary_link_url": "acme.com", "locale": "en", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "ACME Corporation GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" }, "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "company", "id": "company-issuer-uuid", "attributes": { "name": "Service Provider Inc", "description": "Professional services company", "domain_name_primary_link_url": "serviceprovider.com", "locale": "en", "tax_id": { "value": "FR987654321", "type": "VAT" }, "registration": { "trade_name": "Service Provider", "registered_name": "Service Provider Inc." }, "registration_number": { "business_type": "Inc", "value": "RCS 987654", "registry_name": "Paris Commercial Registry", "registry_country": "FR" }, "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } } ] } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "missing_required_fields": { "summary": "Missing required invoice fields", "value": { "error": { "message": "Missing required fields", "code": "validation_error", "details": { "missing_fields": [ "reference_number", "issue_date", "local_currency" ], "provided_data": { "due_date": "2025-02-15" } } } } }, "invalid_currency": { "summary": "Invalid currency code provided", "value": { "error": { "message": "Invalid currency code", "code": "validation_error", "details": { "field": "local_currency", "provided_value": "INVALID", "allowed_values": [ "EUR", "USD", "GBP", "CHF" ] } } } }, "invalid_date_range": { "summary": "Due date before issue date", "value": { "error": { "message": "Due date must be after issue date", "code": "validation_error", "details": { "issue_date": "2025-01-15", "due_date": "2025-01-10", "field": "due_date" } } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/invoices/{id}": { "patch": { "summary": "Update an invoice", "description": "Modify an existing invoice by its unique ID.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the invoice to be updated." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePatch" } } } }, "responses": { "200": { "description": "Invoice updated successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceResponse" } } }, "example": { "data": { "type": "invoice", "id": "invoice_550e8400-e29b-41d4-a716-446655440000", "attributes": { "reference_number": "INV-2025-001", "document_type": "commercial_invoice", "document_type_code": "380", "issue_date": "2025-01-15", "due_date": "2025-02-15", "local_currency": "EUR", "local_totals": { "subtotal": "1000.00", "tax_total": "200.00", "total_amount": "1200.00" }, "terms": "Payment due within 30 days", "billing_context": "subscription", "payment_status": { "paid": true, "amount_paid": 123, "amount_remaining": 123 }, "status": "draft", "description": "Professional services invoice for January 2025", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" }, "relationships": { "issuer": { "data": { "type": "company", "id": "company-issuer-uuid" } }, "receiver": { "data": { "type": "company", "id": "company-receiver-uuid" } }, "payment_means": { "data": [ { "type": "payment_means", "id": "pm_1" } ] }, "invoice_items": { "data": [ { "type": "invoice_item", "id": "item_1" } ] }, "document": { "data": { "type": "document", "id": "doc_original_invoice" } }, "people": { "data": [ { "type": "people", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" } ] } } }, "included": [ { "type": "people", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "attributes": { "first_name": "John", "last_name": "Smith", "full_name": "John Smith", "email": "jsmith@example.com", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "document", "id": "doc_original_invoice", "attributes": { "file_name": "invoice_2025_001.pdf", "status": "processed", "uploaded_at": "2023-11-07T05:31:56Z", "processed_at": "2023-11-07T05:31:56Z", "file_type": "application/pdf", "size_bytes": 245678, "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "invoice_item", "id": "item_1", "attributes": { "line_id": "1", "sku": "WM-1001", "name": "Wireless Mouse", "description": "Ergonomic wireless mouse with USB receiver", "unit_price": 25, "currency": "EUR", "unit": "EA", "min_quantity": 1, "max_quantity": 500, "tax": { "rate": 20, "category": "standard", "scheme": "VAT" }, "period": { "start": "2025-06-26", "end": "2025-06-27" }, "created_at": "2025-05-11T13:42:12Z", "updated_at": "2025-05-11T13:45:20Z" } }, { "type": "payment_means", "id": "pm_1", "attributes": { "type": "card_details", "scheme": "SEPA", "status": "active", "account_details": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "account_number": "532013000", "routing_number": "37040044", "currency": "EUR" }, "bank_details": { "bank_name": "Commerzbank AG", "bank_code": "37040044", "branch_name": "Main Branch", "branch_code": "440" }, "card_details": { "masked_pan": "****1234", "brand": "visa", "card_type": "credit", "expiry_month": 12, "expiry_year": 2027, "cardholder_name": "John Smith" }, "digital_wallet": { "provider": "paypal", "wallet_id": "john.smith@example.com", "wallet_type": "personal" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared", "sanctions_check": "passed", "last_compliance_check": "2023-11-07T05:31:56Z" }, "metadata": { "source": "api", "external_id": "ext_pm_12345" }, "nickname": "Primary Payment Method", "description": "Main company payment account", "tags": [ "primary", "sepa" ], "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "company", "id": "company-receiver-uuid", "attributes": { "name": "ACME Corporation", "description": "Technology solutions provider", "domain_name_primary_link_url": "acme.com", "locale": "en", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "ACME Corporation GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" }, "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "company", "id": "company-issuer-uuid", "attributes": { "name": "Service Provider Inc", "description": "Professional services company", "domain_name_primary_link_url": "serviceprovider.com", "locale": "en", "tax_id": { "value": "FR987654321", "type": "VAT" }, "registration": { "trade_name": "Service Provider", "registered_name": "Service Provider Inc." }, "registration_number": { "business_type": "Inc", "value": "RCS 987654", "registry_name": "Paris Commercial Registry", "registry_country": "FR" }, "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } } ] } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/InvoiceNotFound" } } }, "delete": { "summary": "Delete an invoice", "description": "Remove an invoice by its unique ID. This action is irreversible.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the invoice to be deleted." } ], "responses": { "204": { "description": "Invoice deleted successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/InvoiceNotFound" } } }, "get": { "summary": "Retrieve a specific invoice", "description": "Fetch detailed information about a single invoice by ID.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the invoice." }, { "name": "include", "in": "query", "description": "Include related resources (e.g., document)", "schema": { "type": "string", "example": "document" } } ], "responses": { "200": { "description": "Invoice retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceResponse" } } }, "example": { "data": { "type": "invoice", "id": "invoice_550e8400-e29b-41d4-a716-446655440000", "attributes": { "reference_number": "INV-2025-001", "document_type": "commercial_invoice", "document_type_code": "380", "issue_date": "2025-01-15", "due_date": "2025-02-15", "local_currency": "EUR", "local_totals": { "subtotal": "1000.00", "tax_total": "200.00", "total_amount": "1200.00" }, "terms": "Payment due within 30 days", "billing_context": "subscription", "payment_status": { "paid": true, "amount_paid": 123, "amount_remaining": 123 }, "status": "draft", "description": "Professional services invoice for January 2025", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" }, "relationships": { "issuer": { "data": { "type": "company", "id": "company-issuer-uuid" } }, "receiver": { "data": { "type": "company", "id": "company-receiver-uuid" } }, "payment_means": { "data": [ { "type": "payment_means", "id": "pm_1" } ] }, "invoice_items": { "data": [ { "type": "invoice_item", "id": "item_1" } ] }, "documents": { "data": { "type": "document", "id": "doc_original_invoice" } }, "people": { "data": [ { "type": "people", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" } ] } } }, "included": [ { "type": "people", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "attributes": { "first_name": "John", "last_name": "Smith", "full_name": "John Smith", "email": "jsmith@example.com", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "document", "id": "doc_original_invoice", "attributes": { "file_name": "invoice_2025_001.pdf", "status": "processed", "uploaded_at": "2023-11-07T05:31:56Z", "processed_at": "2023-11-07T05:31:56Z", "file_type": "application/pdf", "size_bytes": 245678, "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "invoice_item", "id": "item_1", "attributes": { "line_id": "1", "sku": "WM-1001", "name": "Wireless Mouse", "description": "Ergonomic wireless mouse with USB receiver", "unit_price": 25, "currency": "EUR", "unit": "EA", "min_quantity": 1, "max_quantity": 500, "tax": { "rate": 20, "category": "standard", "scheme": "VAT" }, "period": { "start": "2025-06-26", "end": "2025-06-27" }, "created_at": "2025-05-11T13:42:12Z", "updated_at": "2025-05-11T13:45:20Z" } }, { "type": "payment_means", "id": "pm_1", "attributes": { "type": "card_details", "scheme": "SEPA", "status": "active", "account_details": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "account_number": "532013000", "routing_number": "37040044", "currency": "EUR" }, "bank_details": { "bank_name": "Commerzbank AG", "bank_code": "37040044", "branch_name": "Main Branch", "branch_code": "440" }, "card_details": { "masked_pan": "****1234", "brand": "visa", "card_type": "credit", "expiry_month": 12, "expiry_year": 2027, "cardholder_name": "John Smith" }, "digital_wallet": { "provider": "paypal", "wallet_id": "john.smith@example.com", "wallet_type": "personal" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared", "sanctions_check": "passed", "last_compliance_check": "2023-11-07T05:31:56Z" }, "metadata": { "source": "api", "external_id": "ext_pm_12345" }, "nickname": "Primary Payment Method", "description": "Main company payment account", "tags": [ "primary", "sepa" ], "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "company", "id": "company-receiver-uuid", "attributes": { "name": "ACME Corporation", "description": "Technology solutions provider", "domain_name_primary_link_url": "acme.com", "locale": "en", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "ACME Corporation GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" }, "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } }, { "type": "company", "id": "company-issuer-uuid", "attributes": { "name": "Service Provider Inc", "description": "Professional services company", "domain_name_primary_link_url": "serviceprovider.com", "locale": "en", "tax_id": { "value": "FR987654321", "type": "VAT" }, "registration": { "trade_name": "Service Provider", "registered_name": "Service Provider Inc." }, "registration_number": { "business_type": "Inc", "value": "RCS 987654", "registry_name": "Paris Commercial Registry", "registry_country": "FR" }, "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } } ] } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/InvoiceNotFound" } } } }, "/v1/invoice-items": { "post": { "summary": "Create an invoice item", "description": "Create a new invoice item with detailed product information, pricing, taxes, and period specifications.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceItemPost" }, "example": { "type": "invoice_item", "attributes": { "line_id": "1", "sku": "WM-1001", "name": "Wireless Mouse", "description": "Ergonomic wireless mouse with USB receiver", "unit_price": 25, "currency": "EUR", "unit": "EA", "min_quantity": 1, "max_quantity": 500, "tax": { "rate": 20, "category": "standard", "scheme": "VAT" }, "period": { "start": "2025-06-26", "end": "2025-06-27" } }, "relationships": { "invoices": { "data": [ { "type": "invoice", "id": "invoice1" } ] } } } } } }, "responses": { "201": { "description": "Invoice item created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceItem" }, "example": { "data": { "type": "invoice_item", "id": "item_001", "attributes": { "line_id": "1", "sku": "WM-1001", "name": "Wireless Mouse", "description": "Ergonomic wireless mouse with USB receiver", "unit_price": 25, "currency": "EUR", "unit": "EA", "min_quantity": 1, "max_quantity": 500, "tax": { "rate": 20, "category": "standard", "scheme": "VAT" }, "period": { "start": "2025-06-26", "end": "2025-06-27" }, "created_at": "2025-05-11T13:42:12Z", "updated_at": "2025-05-11T13:45:20Z" }, "relationships": { "invoices": { "data": [ { "type": "invoice", "id": "invoice1" } ] }, "medias": { "data": [ { "type": "media", "id": "media-1" } ] } } }, "included": [ { "type": "invoice", "id": "invoice1", "attributes": { "reference_number": "INV-2025-001", "document_type": "commercial_invoice", "document_type_code": "380", "issue_date": "2025-01-15", "due_date": "2025-02-15", "local_currency": "EUR", "local_totals": { "subtotal": "1000.00", "tax_total": "200.00", "total_amount": "1200.00" }, "terms": "Payment due within 30 days", "billing_context": "subscription", "payment_status": { "paid": false, "amount_paid": 0, "amount_remaining": 1200 }, "status": "draft", "description": "Professional services invoice for January 2025", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" } }, { "type": "media", "id": "media-1", "attributes": { "media_type": "logo", "is_primary": true, "url": "https://cdn.example.com/product-images/wireless-mouse.jpg", "created_at": "2025-05-11T13:00:00Z", "updated_at": "2025-05-11T13:00:00Z" } } ] } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "get": { "operationId": "listInvoiceItems", "summary": "List Invoice Items", "description": "Workspace-scoped, cursor-paginated list of `invoice_item` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of invoice_item records.", "content": { "application/json": { "example": { "data": [ { "type": "invoice_item", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/balances": { "post": { "summary": "Create a balance record", "description": "Create a new balance record with local and accounting currency information, foreign exchange rates, and account relationships.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceCreateRequest" }, "example": { "type": "balance", "attributes": { "local_balance": { "opening_booked": "123.32", "opening_value": "124.42", "closing_booked": "123.32", "closing_value": "124.42", "currency": "USD" }, "accounting_balance": { "opening_booked": "123.32", "opening_value": "124.42", "closing_booked": "123.32", "closing_value": "124.42", "currency": "EUR" }, "foreign_exchange": [ { "currency_rate": "1.2546", "currency_pair": "EURUSD", "currency_rate_source": "European Central Bank", "currency_rate_at": "2025-06-01T14:30:00Z" }, { "currency_rate": "1.2546", "currency_pair": "EURUSD", "currency_rate_source": "European Central Bank", "currency_rate_at": "2025-06-03T14:30:00Z" } ], "balance_at_from": "2025-06-01T10:00:00Z", "balance_at_to": "2025-06-03T10:00:00Z" }, "relationships": { "transactions": { "data": [ { "type": "transaction", "id": "uuid1" } ] }, "account": { "data": { "type": "payment_mean", "id": "uuid2" } }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_tenant" } ] } } } } } }, "responses": { "201": { "description": "Balance created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceCreateResponse" }, "example": { "type": "balance", "id": "balance1", "attributes": { "local_balance": { "opening_booked": "123.32", "opening_value": "124.42", "closing_booked": "123.32", "closing_value": "124.42", "currency": "USD" }, "accounting_balance": { "opening_booked": "123.32", "opening_value": "124.42", "closing_booked": "123.32", "closing_value": "124.42", "currency": "EUR" }, "foreign_exchange": [ { "currency_rate": "1.2546", "currency_pair": "EURUSD", "currency_rate_source": "European Central Bank", "currency_rate_at": "2025-06-01T14:30:00Z" } ], "balance_at_from": "2025-06-01T10:00:00Z", "balance_at_to": "2025-06-03T10:00:00Z" }, "relationships": { "transactions": { "data": [ { "type": "transaction", "id": "uuid1" } ] }, "account": { "data": { "type": "payment_mean", "id": "uuid2" } }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_tenant" } ] } }, "included": { "transaction": [ { "type": "transaction", "id": "uuid1", "attributes": { "scheme": "sepa", "external_ids": { "transaction_id": "TXN_SEPA_20250601_001", "payment_request_id": "PAY_REQ_001", "end_to_end_id": "E2E_20250601_ACME_001" }, "requested_execution_date": "2025-06-01", "executed_at": "2025-06-01T10:30:00Z", "booking_date": "2025-06-01", "value_date": "2025-06-01", "instructed_amount": { "currency": "EUR", "amount": 50 }, "settlement_amount": { "currency": "USD", "amount": 54.25 }, "foreign_exchange": { "currency_rate": "1.0850", "currency_pair": "EURUSD", "currency_rate_source": "European Central Bank", "currency_rate_at": "2025-06-01T10:00:00Z" }, "transaction_type": "transfer", "status": "completed", "category_purpose": "CBFF", "purpose_code": "SALA", "remittance_information": { "unstructured": "Balance related transaction", "structured_reference": "RF18539007547034", "reference_type": "SCOR" }, "fees": [ { "type": "transfer_fee", "amount": 1.5, "currency": "EUR" } ], "created_at": "2025-06-01T10:30:00Z", "updated_at": "2025-06-01T10:30:00Z" } } ], "account": [ { "type": "payment_means", "id": "uuid2", "attributes": { "type": "account_details", "scheme": "ACH", "status": "active", "account_details": { "account_number": "1234567890", "routing_number": "021000021", "account_type": "checking", "currency": "USD" }, "bank_details": { "bank_name": "JPMorgan Chase Bank, N.A.", "bank_code": "CHASUS33", "branch_name": "New York Main Branch", "branch_code": "NY001" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared" }, "nickname": "Main Operating Account", "description": "Primary USD account for operations", "tags": [ "usd", "operating", "primary" ], "created_at": "2025-06-01T10:00:00Z", "updated_at": "2025-06-01T10:00:00Z" } } ], "workspaces": [ { "type": "workspace", "id": "workspace_tenant", "attributes": { "name": "Main Workspace", "description": "Primary workspace for financial operations", "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-01T12:00:00Z", "avatar_color": "#4A90E2", "external_workspace_id": "workspace-001", "auto_extract_enabled": true } } ] } } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/balances/{id}": { "delete": { "summary": "Delete a balance record", "description": "Permanently delete a specific balance record by its unique ID. This action is irreversible and will remove all associated balance data including local balance, accounting balance, and foreign exchange information.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the balance record to delete", "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "204": { "description": "Balance record successfully deleted (no content returned)" }, "400": { "description": "Bad Request - Invalid balance ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid_uuid": { "summary": "Invalid UUID format", "value": { "errors": [ { "status": "400", "title": "Invalid ID Format", "detail": "The balance ID must be a valid UUID format", "source": { "parameter": "id" } } ] } } } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Not found - related entity does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "holder_not_found", "status": "404", "code": "HOLDER_NOT_FOUND", "title": "Holder Not Found", "detail": "The specified holder company or person does not exist", "source": { "pointer": "/data/relationships/holder/data/id" } } ] } } } } }, "tags": [ "Balances" ], "operationId": "deleteBalance" } }, "/v1/invoice-items/{id}": { "patch": { "summary": "Create an invoice item", "description": "Create a new invoice item with detailed product information, pricing, taxes, and period specifications.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceItemPatch" }, "example": { "type": "invoice_item", "attributes": { "line_id": "1", "sku": "WM-1001", "name": "Wireless Mouse", "description": "Ergonomic wireless mouse with USB receiver", "unit_price": 25, "currency": "EUR", "unit": "EA", "min_quantity": 1, "max_quantity": 500, "tax": { "rate": 20, "category": "standard", "scheme": "VAT" }, "period": { "start": "2025-06-26", "end": "2025-06-27" } }, "relationships": { "invoices": { "data": [ { "type": "invoice", "id": "invoice1" } ] } } } } } }, "responses": { "201": { "description": "Invoice item created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceItem" }, "example": { "data": { "type": "invoice_item", "id": "item_001", "attributes": { "line_id": "1", "sku": "WM-1001", "name": "Wireless Mouse", "description": "Ergonomic wireless mouse with USB receiver", "unit_price": 25, "currency": "EUR", "unit": "EA", "min_quantity": 1, "max_quantity": 500, "tax": { "rate": 20, "category": "standard", "scheme": "VAT" }, "period": { "start": "2025-06-26", "end": "2025-06-27" }, "created_at": "2025-05-11T13:42:12Z", "updated_at": "2025-05-11T13:45:20Z" }, "relationships": { "invoices": { "data": [ { "type": "invoice", "id": "invoice1" } ] }, "medias": { "data": [ { "type": "media", "id": "media-1" } ] } } }, "included": [ { "type": "invoice", "id": "invoice1", "attributes": { "reference_number": "INV-2025-001", "document_type": "commercial_invoice", "document_type_code": "380", "issue_date": "2025-01-15", "due_date": "2025-02-15", "local_currency": "EUR", "local_totals": { "subtotal": "1000.00", "tax_total": "200.00", "total_amount": "1200.00" }, "terms": "Payment due within 30 days", "billing_context": "subscription", "payment_status": { "paid": false, "amount_paid": 0, "amount_remaining": 1200 }, "status": "draft", "description": "Professional services invoice for January 2025", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" } }, { "type": "media", "id": "media-1", "attributes": { "media_type": "logo", "is_primary": true, "url": "https://cdn.example.com/product-images/wireless-mouse.jpg", "created_at": "2025-05-11T13:00:00Z", "updated_at": "2025-05-11T13:00:00Z" } } ] } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "delete": { "summary": "Delete an invoice item", "description": "Permanently delete a specific invoice item by ID. This action cannot be undone.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the invoice item to delete" } ], "responses": { "204": { "description": "Invoice item successfully deleted (no content returned)" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Not found - related entity does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "holder_not_found", "status": "404", "code": "HOLDER_NOT_FOUND", "title": "Holder Not Found", "detail": "The specified holder company or person does not exist", "source": { "pointer": "/data/relationships/holder/data/id" } } ] } } } } }, "tags": [ "Invoice Items" ], "operationId": "deleteInvoiceItem" }, "get": { "operationId": "getInvoiceItems", "summary": "Get invoice item", "description": "Fetch one `invoice_item` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The invoice_item record.", "content": { "application/json": { "example": { "data": { "type": "invoice_item", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "invoice_item not found / not in workspace scope." } } } }, "/v1/companies": { "post": { "operationId": "createCompany", "summary": "Create a new company", "description": "Create a new company record with comprehensive business information, registration details, tax information, and various relationships including people, workspaces, and other entities.", "tags": [ "Companies" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyPost" }, "example": { "type": "company", "attributes": { "description": "Enterprise open source solutions company.", "locale": "en", "domain_name_primary_link_url": "acme.com", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "Tech Solutions GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" } }, "relationships": { "created_by": { "data": { "type": "people", "id": "people1" } }, "media": { "data": [ { "type": "media", "id": "media1" } ] }, "web_links": { "data": [ { "type": "web_link", "id": "sl1" } ] }, "emails": { "data": [ { "type": "email", "id": "email1" } ] }, "phones": { "data": [ { "type": "phone", "id": "phone1" } ] }, "locations": { "data": [ { "type": "location", "id": "loc1" } ] }, "people": { "data": [ { "type": "people", "id": "people1", "meta": { "relationship_type": "owner" } } ] }, "parents": { "data": { "type": "company", "id": "parent_company1" } }, "subsidiaries": { "data": [ { "type": "company", "id": "subsidiary1" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_tenant" } ] } }, "included": [ { "type": "people", "id": "people1", "attributes": { "first_name": "John", "last_name": "Doe", "full_name": "John Doe" } }, { "type": "media", "id": "media1", "attributes": { "file_name": "company_logo.png", "media_type": "logo", "is_primary": true } }, { "type": "web_link", "id": "sl1", "attributes": { "url": "https://www.linkedin.com/company/acme", "platform": "linkedin" } }, { "type": "email", "id": "email1", "attributes": { "value": "contact@acme.com", "label": "work", "is_primary": true } }, { "type": "phone", "id": "phone1", "attributes": { "e164_number": "+33123456789", "label": "work", "is_primary": true } }, { "type": "location", "id": "loc1", "attributes": { "street": "123 Tech Street", "city": "Berlin", "postal_code": "10115", "country": "DE", "is_primary": true } }, { "type": "workspace", "id": "workspace_tenant", "attributes": { "name": "Main Workspace", "description": "Primary workspace for ACME operations" } }, { "type": "company", "id": "parent_company1", "attributes": { "name": "ACME Global Holdings", "description": "Parent company of ACME", "registration": { "registered_name": "ACME Global Holdings GmbH" } } }, { "type": "company", "id": "subsidiary1", "attributes": { "name": "ACME France", "description": "French subsidiary of ACME", "registration": { "registered_name": "ACME France SAS" } } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016", "attributes": { "name": "company_registration.pdf", "file_size": 245678, "content_type": "application/pdf", "created_at": "2025-09-25T10:00:00.000Z" } } ] } } } }, "responses": { "201": { "description": "Company created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyPostResponse" } } }, "example": { "data": { "type": "company", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "attributes": { "description": "Enterprise open source solutions company.", "locale": "en", "domain_name_primary_link_url": "acme.com", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "Tech Solutions GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" }, "created_at": "2025-09-30T14:30:00.000Z", "updated_at": "2025-09-30T14:30:00.000Z" }, "relationships": { "created_by": { "data": { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } }, "media": { "data": [ { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010" } ] }, "web_links": { "data": [ { "type": "web_link", "id": "550e8400-e29b-41d4-a716-446655440011" } ] }, "emails": { "data": [ { "type": "email", "id": "550e8400-e29b-41d4-a716-446655440012" } ] }, "phones": { "data": [ { "type": "phone", "id": "550e8400-e29b-41d4-a716-446655440013" } ] }, "locations": { "data": [ { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440015" } ] }, "people": { "data": [ { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } ] }, "documents": { "data": [ { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016" } ] }, "parents": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440019" } }, "subsidiaries": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440020" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001" } ] } } }, "included": [ { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "attributes": { "first_name": "Alexandre", "last_name": "Dubois", "full_name": "Alexandre Dubois", "relationship_type": "owner" } }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "Development Team", "description": "Main development workspace for software engineering projects and client solutions", "created_at": "2025-09-10T08:00:00.000Z", "updated_at": "2025-09-15T16:45:00.000Z" } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "company_logo.png", "content_type": "image/png", "file_size": 15678 } }, { "type": "web_link", "id": "550e8400-e29b-41d4-a716-446655440011", "attributes": { "url": "https://www.linkedin.com/company/acme", "platform": "linkedin" } }, { "type": "email", "id": "550e8400-e29b-41d4-a716-446655440012", "attributes": { "value": "contact@acme.com", "label": "work", "is_primary": true } }, { "type": "phone", "id": "550e8400-e29b-41d4-a716-446655440013", "attributes": { "e164_number": "+4930123456789", "label": "work", "is_primary": true } }, { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440015", "attributes": { "street": "Unter den Linden 1", "city": "Berlin", "postal_code": "10117", "country": "DE", "is_primary": true } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016", "attributes": { "name": "company_registration.pdf", "file_size": 245678, "content_type": "application/pdf", "created_at": "2025-09-25T10:00:00.000Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440019", "attributes": { "name": "ACME Global Holdings", "description": "Parent company of ACME", "registration": { "registered_name": "ACME Global Holdings GmbH" } } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440020", "attributes": { "name": "ACME France", "description": "French subsidiary of ACME", "registration": { "registered_name": "ACME France SAS" } } } ] } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "missing_required_field": { "summary": "Missing required registered_name", "value": { "code": "VALIDATION_ERROR", "status": 400, "title": "Validation Error", "message": "The registration.registered_name field is required", "meta": { "log_id": "550e8400-e29b-41d4-a716-446655440999", "errors": [ { "field": "registration.registered_name", "code": "REQUIRED", "message": "This field is required" } ] } } }, "invalid_tax_id_format": { "summary": "Invalid tax ID format", "value": { "code": "VALIDATION_ERROR", "status": 400, "title": "Validation Error", "message": "Invalid tax ID format for the specified type", "meta": { "log_id": "550e8400-e29b-41d4-a716-446655440998", "errors": [ { "field": "tax_id.value", "code": "INVALID_FORMAT", "message": "VAT number format is invalid for the specified country" } ] } } } } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "get": { "operationId": "listCompanies", "summary": "Get all companies", "description": "Retrieve a paginated list of companies. By default, only basic company data is returned with relationship IDs. Use the 'include' parameter to get detailed relationship data.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "workspace", "company", "people", "documents", "created_by", "medias", "web_links", "emails", "phones", "categories", "locations", "people", "parents", "subsidiaries" ] }, "description": "Include detailed relationship data in the response. Comma-separated values supported.", "example": "workspace,people,emails" }, { "name": "filter[created_at_from]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter companies created on or after this date", "example": "2025-01-01T00:00:00Z" }, { "name": "filter[created_at_to]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter companies created on or before this date", "example": "2025-12-31T23:59:59Z" }, { "name": "filter[updated_at_from]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter companies updated on or after this date", "example": "2025-01-01T00:00:00Z" }, { "name": "filter[updated_at_to]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter companies updated on or before this date", "example": "2025-12-31T23:59:59Z" }, { "name": "filter[created_by]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": "Filter companies by creator ID(s)", "example": [ "550e8400-e29b-41d4-a716-446655440000" ] }, { "name": "filter[workspace_id]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": "Filter companies by workspace ID(s)", "example": [ "550e8400-e29b-41d4-a716-446655440001" ] }, { "name": "filter[external_workspace_id]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter companies by external workspace ID(s)", "example": [ "ext-workspace-123" ] }, { "name": "filter[emails]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "email" } }, "description": "Filter companies by email address(es)", "example": [ "contact@company.com" ] }, { "name": "filter[phone]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter companies by phone number(s)", "example": [ "+1234567890" ] }, { "name": "filter[parent_registration]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter companies by parent registration number(s)", "example": [ "HRB123456" ] }, { "name": "filter[documents_id]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": "Filter companies by associated document ID(s)", "example": [ "550e8400-e29b-41d4-a716-446655440002" ] }, { "name": "filter[parents_company_id]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": "Filter companies by parent company ID(s)", "example": [ "550e8400-e29b-41d4-a716-446655440003" ] }, { "name": "filter[parents_company_tax_id_value]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter companies by parent company tax ID value(s)", "example": [ "DE123456789" ] }, { "name": "filter[parents_company_registration_registered_value]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter companies by parent company registration value(s)", "example": [ "123456789" ] }, { "name": "filter[domain_name_primary_link_url]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uri" } }, "description": "Filter companies by primary domain URL(s)", "example": [ "acme.com" ] }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "issue_date", "-issue_date", "due_date", "-due_date" ] }, "description": "Sort companies by field. Use - prefix for descending order.", "example": "-created_at" } ], "responses": { "200": { "description": "Companies retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyPostResponse" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } }, "example": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "name": "TechCorp Solutions GmbH", "description": "Leading technology company specializing in AI solutions and business automation", "business_entity": "GmbH", "registration": { "tax_id": "12345678901", "registered_value": "123456789", "country": "DE" }, "registration_number": { "value": "HRB 123456", "authority": "Amtsgericht M\u00fcnchen" }, "has_logo": true, "workspace_id": [ "550e8400-e29b-41d4-a716-446655440004" ], "created_at": "2024-08-15T10:30:00Z", "updated_at": "2024-12-01T14:22:00Z" }, "relationships": { "created_by": { "data": { "type": "user", "id": "550e8400-e29b-41d4-a716-446655440020" } }, "people": { "data": [ { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440001" } ] }, "emails": { "data": [ { "type": "email", "id": "550e8400-e29b-41d4-a716-446655440010" } ] }, "phones": { "data": [ { "type": "phone", "id": "550e8400-e29b-41d4-a716-446655440011" } ] }, "web_links": { "data": [ { "type": "web_link", "id": "550e8400-e29b-41d4-a716-446655440012" } ] }, "media": { "data": [ { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440014" } ] }, "documents": { "data": [ { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016" } ] }, "locations": { "data": [ { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440013" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440004" } ] }, "parents": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440017" } ] }, "subsidiaries": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440018" } ] } } } ], "included": [ { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "first_name": "Klaus", "last_name": "Weber", "full_name": "Klaus Weber", "relationship_type": "owner", "job_title": "Founder & CEO" } }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440004", "attributes": { "name": "European Operations", "description": "Main workspace for European business operations", "created_at": "2024-01-10T08:15:00Z" } }, { "type": "email", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "value": "contact@techcorp.com", "label": "work", "is_verified": true, "is_primary": true } }, { "type": "phone", "id": "550e8400-e29b-41d4-a716-446655440011", "attributes": { "value": "+491234567890", "label": "work", "is_verified": true, "is_primary": true } }, { "type": "web_link", "id": "550e8400-e29b-41d4-a716-446655440012", "attributes": { "url": "https://www.linkedin.com/company/techcorp-solutions", "platform": "linkedin", "is_primary": true } }, { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440013", "attributes": { "street": "Maximilianstrasse 123", "city": "M\u00fcnchen", "postal_code": "80539", "country": "DE", "is_primary": true, "is_registered": true } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440014", "attributes": { "url": "https://cdn.techcorp.com/logo.png", "media_type": "logo", "is_primary": true } }, { "type": "user", "id": "550e8400-e29b-41d4-a716-446655440020", "attributes": { "first_name": "John", "last_name": "Doe", "email": "john.doe@techcorp.com", "created_at": "2024-01-05T09:00:00Z" } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016", "attributes": { "name": "Company Registration Certificate", "file_name": "registration_certificate.pdf", "mime_type": "application/pdf", "size": 245760, "is_public": false, "created_at": "2024-08-15T10:30:00Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440017", "attributes": { "name": "Global Tech Holdings", "description": "Parent company of TechCorp Solutions", "business_entity": "AG", "relationship_type": "parent" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440018", "attributes": { "name": "TechCorp Software Labs", "description": "R&D subsidiary specializing in software development", "business_entity": "GmbH", "relationship_type": "subsidiary" } } ], "meta": { "pagination": { "total": 2, "count": 2, "per_page": 25, "current_page": 1, "total_pages": 1 } } } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/companies/{id}": { "get": { "summary": "Get a specific company", "description": "Retrieve a specific company by ID", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the company to retrieve" } ], "responses": { "200": { "description": "Company retrieved successfully", "content": { "application/json": { "example": { "data": { "type": "company", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "attributes": { "description": "Enterprise open source solutions company.", "locale": "en", "domain_name_primary_link_url": "acme.com", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "Tech Solutions GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" }, "created_at": "2025-09-30T14:30:00.000Z", "updated_at": "2025-09-30T14:30:00.000Z" }, "relationships": { "created_by": { "data": { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } }, "media": { "data": [ { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010" } ] }, "web_links": { "data": [ { "type": "web_link", "id": "550e8400-e29b-41d4-a716-446655440011" } ] }, "emails": { "data": [ { "type": "email", "id": "550e8400-e29b-41d4-a716-446655440012" } ] }, "phones": { "data": [ { "type": "phone", "id": "550e8400-e29b-41d4-a716-446655440013" } ] }, "locations": { "data": [ { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440015" } ] }, "people": { "data": [ { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } ] }, "documents": { "data": [ { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016" } ] }, "parents": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440019" } }, "subsidiaries": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440020" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001" } ] } } }, "included": [ { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "attributes": { "first_name": "Alexandre", "last_name": "Dubois", "full_name": "Alexandre Dubois", "relationship_type": "owner" } }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "Development Team", "description": "Main development workspace for software engineering projects and client solutions", "created_at": "2025-09-10T08:00:00.000Z", "updated_at": "2025-09-15T16:45:00.000Z" } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "company_logo.png", "content_type": "image/png", "file_size": 15678 } }, { "type": "web_link", "id": "550e8400-e29b-41d4-a716-446655440011", "attributes": { "url": "https://www.linkedin.com/company/acme", "platform": "linkedin" } }, { "type": "email", "id": "550e8400-e29b-41d4-a716-446655440012", "attributes": { "value": "contact@acme.com", "label": "work", "is_primary": true } }, { "type": "phone", "id": "550e8400-e29b-41d4-a716-446655440013", "attributes": { "e164_number": "+4930123456789", "label": "work", "is_primary": true } }, { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440015", "attributes": { "street": "Unter den Linden 1", "city": "Berlin", "postal_code": "10117", "country": "DE", "is_primary": true } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016", "attributes": { "name": "company_registration.pdf", "file_size": 245678, "content_type": "application/pdf", "created_at": "2025-09-25T10:00:00.000Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440019", "attributes": { "name": "ACME Global Holdings", "description": "Parent company of ACME", "registration": { "registered_name": "ACME Global Holdings GmbH" } } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440020", "attributes": { "name": "ACME France", "description": "French subsidiary of ACME", "registration": { "registered_name": "ACME France SAS" } } } ] }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyPostResponse" } } } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/CompanyNotFound" } } }, "patch": { "summary": "Update a company", "description": "Update an existing company record", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the company to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyPatchRequest" }, "example": { "type": "company", "attributes": { "description": "Enterprise open source solutions company.", "locale": "en", "domain_name_primary_link_url": "acme.com", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "Tech Solutions GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" } }, "relationships": { "created_by": { "data": { "type": "people", "id": "people1" } }, "media": { "data": [ { "type": "media", "id": "media1" } ] }, "web_links": { "data": [ { "type": "web_link", "id": "sl1" } ] }, "emails": { "data": [ { "type": "email", "id": "email1" } ] }, "phones": { "data": [ { "type": "phone", "id": "phone1" } ] }, "locations": { "data": [ { "type": "location", "id": "loc1" } ] }, "people": { "data": [ { "type": "people", "id": "people1", "meta": { "relationship_type": "owner" } } ] }, "parents": { "data": { "type": "company", "id": "parent_company1" } }, "subsidiaries": { "data": [ { "type": "company", "id": "subsidiary1" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_tenant" } ] } }, "included": [ { "type": "people", "id": "people1", "attributes": { "first_name": "John", "last_name": "Doe", "full_name": "John Doe" } }, { "type": "media", "id": "media1", "attributes": { "file_name": "company_logo.png", "media_type": "logo", "is_primary": true } }, { "type": "web_link", "id": "sl1", "attributes": { "url": "https://www.linkedin.com/company/acme", "platform": "linkedin" } }, { "type": "email", "id": "email1", "attributes": { "value": "contact@acme.com", "label": "work", "is_primary": true } }, { "type": "phone", "id": "phone1", "attributes": { "e164_number": "+33123456789", "label": "work", "is_primary": true } }, { "type": "location", "id": "loc1", "attributes": { "street": "123 Tech Street", "city": "Berlin", "postal_code": "10115", "country": "DE", "is_primary": true } }, { "type": "workspace", "id": "workspace_tenant", "attributes": { "name": "Main Workspace", "description": "Primary workspace for ACME operations" } }, { "type": "company", "id": "parent_company1", "attributes": { "name": "ACME Global Holdings", "description": "Parent company of ACME", "registration": { "registered_name": "ACME Global Holdings GmbH" } } }, { "type": "company", "id": "subsidiary1", "attributes": { "name": "ACME France", "description": "French subsidiary of ACME", "registration": { "registered_name": "ACME France SAS" } } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016", "attributes": { "name": "company_registration.pdf", "file_size": 245678, "content_type": "application/pdf", "created_at": "2025-09-25T10:00:00.000Z" } } ] } } } }, "responses": { "200": { "description": "Company updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyPostResponse" } } }, "example": { "data": { "type": "company", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "attributes": { "description": "Enterprise open source solutions company.", "locale": "en", "domain_name_primary_link_url": "acme.com", "tax_id": { "value": "DE123456789", "type": "VAT" }, "registration": { "trade_name": "TechSol", "registered_name": "Tech Solutions GmbH" }, "registration_number": { "business_type": "GmbH", "value": "HRB 123456", "registry_name": "Handelsregister Berlin", "registry_country": "DE" }, "created_at": "2025-09-30T14:30:00.000Z", "updated_at": "2025-09-30T14:30:00.000Z" }, "relationships": { "created_by": { "data": { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } }, "media": { "data": [ { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010" } ] }, "web_links": { "data": [ { "type": "web_link", "id": "550e8400-e29b-41d4-a716-446655440011" } ] }, "emails": { "data": [ { "type": "email", "id": "550e8400-e29b-41d4-a716-446655440012" } ] }, "phones": { "data": [ { "type": "phone", "id": "550e8400-e29b-41d4-a716-446655440013" } ] }, "locations": { "data": [ { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440015" } ] }, "people": { "data": [ { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } ] }, "documents": { "data": [ { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016" } ] }, "parents": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440019" } }, "subsidiaries": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440020" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001" } ] } } }, "included": [ { "type": "people", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "attributes": { "first_name": "Alexandre", "last_name": "Dubois", "full_name": "Alexandre Dubois", "relationship_type": "owner" } }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "Development Team", "description": "Main development workspace for software engineering projects and client solutions", "created_at": "2025-09-10T08:00:00.000Z", "updated_at": "2025-09-15T16:45:00.000Z" } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "company_logo.png", "content_type": "image/png", "file_size": 15678 } }, { "type": "web_link", "id": "550e8400-e29b-41d4-a716-446655440011", "attributes": { "url": "https://www.linkedin.com/company/acme", "platform": "linkedin" } }, { "type": "email", "id": "550e8400-e29b-41d4-a716-446655440012", "attributes": { "value": "contact@acme.com", "label": "work", "is_primary": true } }, { "type": "phone", "id": "550e8400-e29b-41d4-a716-446655440013", "attributes": { "e164_number": "+4930123456789", "label": "work", "is_primary": true } }, { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440015", "attributes": { "street": "Unter den Linden 1", "city": "Berlin", "postal_code": "10117", "country": "DE", "is_primary": true } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440016", "attributes": { "name": "company_registration.pdf", "file_size": 245678, "content_type": "application/pdf", "created_at": "2025-09-25T10:00:00.000Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440019", "attributes": { "name": "ACME Global Holdings", "description": "Parent company of ACME", "registration": { "registered_name": "ACME Global Holdings GmbH" } } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440020", "attributes": { "name": "ACME France", "description": "French subsidiary of ACME", "registration": { "registered_name": "ACME France SAS" } } } ] } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/CompanyNotFound" } } }, "delete": { "summary": "Delete a company", "description": "Delete a company record", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the company to delete" } ], "responses": { "204": { "description": "Company deleted successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/CompanyNotFound" } } } }, "/v1/web-links": { "get": { "operationId": "listWebLinks", "summary": "List Web Links", "description": "Workspace-scoped, cursor-paginated list of `social_link` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of social_link records.", "content": { "application/json": { "example": { "data": [ { "type": "social_link", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } }, "post": { "summary": "Create web-link", "description": "Create a web or social media link and associate it with people, companies, or workspaces.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "type": "web_link", "attributes": { "platform": "linkedin", "url": "https://linkedin.com/in/ada" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "people1" } ] }, "companies": { "data": [ { "type": "company", "id": "company_tenant" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_tenant" } ] } } }, "schema": { "$ref": "#/components/schemas/WebLinkCreateRequest" } } } }, "responses": { "201": { "description": "Web link created successfully", "content": { "application/json": { "example": { "type": "social_link", "id": "sl1", "attributes": { "platform": "linkedin", "url": "https://linkedin.com/in/ada", "created_at": "2025-06-01T10:00:00Z", "updated_at": "2025-06-01T10:00:00Z" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "people1" } ] }, "companies": { "data": [ { "type": "company", "id": "company_tenant" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_tenant" } ] } } }, "schema": { "$ref": "#/components/schemas/WebLinkCreateResponse" } } } }, "400": { "description": "Bad request - invalid data" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/CompanyNotFound" } } } }, "/v1/web-links/{id}": { "get": { "operationId": "getWebLinks", "summary": "Get social link", "description": "Fetch one `social_link` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The social_link record.", "content": { "application/json": { "example": { "data": { "type": "social_link", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "social_link not found / not in workspace scope." } } }, "delete": { "summary": "Delete web link", "description": "Delete a web link by ID", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Web link ID to delete", "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "204": { "description": "Web link deleted successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/WebLinkNotFound" } } } }, "/v1/companies/{companyId}/relationships/workspace/{workspaceId}": { "delete": { "summary": "Remove workspace from company", "description": "Remove a workspace relationship from a company. This operation soft-deletes the relationship between the company and workspace.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the company to remove workspace from" }, { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the workspace to remove from the company" } ], "responses": { "204": { "description": "Workspace relationship removed successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/CompanyNotFound" } } } }, "/v1/locations": { "post": { "summary": "Create location", "description": "Create a new address/location with geographic coordinates and associate it with people, companies, or workspaces.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationCreateRequest" }, "example": { "type": "location", "attributes": { "address_line1": "123 Turing Way", "address_line2": "", "city": "London", "region": "Greater London", "postal_code": "E1 6AN", "country": "GB", "latitude": 37.7749, "longitude": -122.4194, "is_primary": true, "is_registered": true }, "relationships": { "persons": { "data": [ { "type": "people", "id": "people1" } ] }, "companies": { "data": [ { "type": "company", "id": "company_tenant" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_tenant" } ] } } } } } }, "responses": { "201": { "description": "Location created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationCreateResponse" }, "example": { "data": { "type": "location", "id": "loc1", "attributes": { "full_address": "123 Turing Way, London, Greater London, E1 6AN, GB", "address_line1": "123 Turing Way", "address_line2": "", "city": "London", "region": "Greater London", "postal_code": "E1 6AN", "country": "GB", "latitude": 37.7749, "longitude": -122.4194, "is_primary": true, "is_registered": true, "created_at": "2025-06-01T10:00:00Z", "updated_at": "2025-06-01T10:00:00Z" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "people1" } ] }, "companies": { "data": [ { "type": "company", "id": "company_tenant" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_tenant" } ] } } }, "included": [ { "type": "people", "id": "people1", "attributes": { "first_name": "Alan", "last_name": "Turing", "full_name": "Alan Turing", "created_at": "2025-06-01T09:00:00Z", "updated_at": "2025-06-01T09:00:00Z" } }, { "type": "company", "id": "company_tenant", "attributes": { "name": "Tech Innovations Ltd", "description": "Leading technology research company", "locale": "en", "domain_name_primary_link_url": "techinnovations.com", "tax_id": { "value": "GB123456789", "type": "VAT" }, "registration": { "trade_name": "Tech Innovations", "registered_name": "Tech Innovations Limited" }, "registration_number": { "business_type": "Ltd", "value": "12345678", "registry_name": "Companies House", "registry_country": "GB" }, "created_at": "2025-05-15T08:00:00Z", "updated_at": "2025-05-15T08:00:00Z" } }, { "type": "workspace", "id": "workspace_tenant", "attributes": { "name": "UK Operations Workspace", "description": "Workspace for UK-based operations and teams", "avatar_color": "#2E86AB", "external_workspace_id": "uk_ops_ws_001", "auto_extract_enabled": true, "created_at": "2025-05-20T10:00:00Z", "updated_at": "2025-05-20T10:00:00Z" } } ] } } } }, "400": { "description": "Bad request - invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "get": { "operationId": "listLocations", "summary": "List Locations", "description": "Workspace-scoped, cursor-paginated list of `location` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of location records.", "content": { "application/json": { "example": { "data": [ { "type": "location", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/locations/{id}": { "get": { "operationId": "getLocations", "summary": "Get location", "description": "Fetch one `location` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The location record.", "content": { "application/json": { "example": { "data": { "type": "location", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "location not found / not in workspace scope." } } }, "delete": { "summary": "Delete location", "description": "Remove a location from a person, company, or workspace", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the location to delete" } ], "responses": { "204": { "description": "Location deleted successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/LocationNotFound" } } } }, "/v1/people": { "get": { "summary": "List people", "description": "Returns the workspace's people (contacts), page-paginated. This endpoint takes only `page` and `limit` — it does not accept inline filtering or sorting. For filtering and sorting (including across related objects), use `POST /v1/records/query` with `root: \"people\"`; see Filtering & sorting.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "People per page (max 100)." } ], "responses": { "200": { "description": "A page of people.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 137 }, "total_pages": { "type": "integer", "example": 7 } }, "required": [ "page", "limit", "total", "total_pages" ] } } } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required or invalid API key." } } }, "post": { "summary": "Create a new person", "description": "Create a new person record with optional emails, phone numbers, company relationships, and social links. If a person with the same name and primary email already exists, returns the existing person instead of creating a duplicate.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" }, "examples": { "complete_person_request": { "summary": "Create person with all optional fields", "description": "Example showing how to create a person with emails, phone numbers, company relationships, and social links. Note: 'label' defaults to 'work' for both emails and phones if not specified. 'is_primary' defaults to 'false', but becomes 'true' automatically if no other email/phone is marked as primary. Only one email and one phone can be marked as primary per person.", "value": { "type": "people", "attributes": { "first_name": "Sophie", "last_name": "Martin" }, "relationships": { "emails": { "data": [ { "type": "email", "id": "temp-email-1" }, { "type": "email", "id": "temp-email-2" } ] }, "phones": { "data": [ { "type": "phone", "id": "temp-phone-1" } ] }, "social_links": { "data": [ { "type": "social_link", "id": "temp-social-1" } ] }, "companies": { "data": [ { "type": "company", "id": "temp-company-1", "meta": { "relationship_type": "employee" } } ] } }, "included": [ { "type": "email", "id": "temp-email-1", "attributes": { "value": "sophie.martin@example.com", "label": "work", "is_primary": true } }, { "type": "email", "id": "temp-email-2", "attributes": { "value": "sophie@personal.com", "label": "personal", "is_primary": false } }, { "type": "phone", "id": "temp-phone-1", "attributes": { "e164_number": "+33123456789", "label": "mobile", "is_primary": true } }, { "type": "social_link", "id": "temp-social-1", "attributes": { "url": "https://linkedin.com/in/sophie-martin", "platform": "linkedin" } }, { "type": "company", "id": "temp-company-1", "attributes": { "name": "Example Corp", "description": "Tech company", "workspace_id": "550e8400-e29b-41d4-a716-446655440001" } } ] } } } } } }, "responses": { "201": { "description": "Person created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleResponse" }, "examples": { "complete_person": { "summary": "Person with all optional fields", "value": { "data": { "type": "people", "id": "3e29b483-e8a0-4871-906e-5ddfc9b7ed6b", "attributes": { "first_name": "Sophie", "last_name": "Martin", "full_name": "Sophie Martin", "created_at": "2025-09-15T14:09:40.942Z" }, "relationships": { "emails": { "data": [ { "type": "email", "id": "471604cd-8de8-4576-97f7-7c4656d7b6b4" }, { "type": "email", "id": "9cbefca9-32bb-48d0-aeee-c07fa84ad0b8" } ] }, "phones": { "data": [ { "type": "phone", "id": "11175a7a-df1a-4f9d-bb2a-9d6023f15bf8" }, { "type": "phone", "id": "ae72063c-861f-489e-973d-83e31cef24f8" } ] }, "social_links": { "data": [ { "type": "social_link", "id": "c401d53e-ca36-47e7-a861-83443599eb4c" } ] }, "companies": { "data": [ { "type": "company", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77a" } ] } } }, "included": [ { "type": "email", "id": "471604cd-8de8-4576-97f7-7c4656d7b6b4", "attributes": { "value": "sophie.perso@gmail.com", "label": "personal", "is_primary": false, "created_at": "2025-09-15T14:09:40.963Z" } }, { "type": "email", "id": "9cbefca9-32bb-48d0-aeee-c07fa84ad0b8", "attributes": { "value": "sophie.martin@company.com", "label": "work", "is_primary": true, "created_at": "2025-09-15T14:09:40.953Z" } }, { "type": "phone", "id": "11175a7a-df1a-4f9d-bb2a-9d6023f15bf8", "attributes": { "e164_number": "+33646020535", "country_code": 33, "national_number": "646020535", "is_primary": true, "is_verify": false, "label": "mobile", "created_at": "2025-09-15T14:09:40.973Z" } }, { "type": "phone", "id": "ae72063c-861f-489e-973d-83e31cef24f8", "attributes": { "e164_number": "+33142356789", "country_code": 33, "national_number": "142356789", "is_primary": false, "is_verify": false, "label": "work", "created_at": "2025-09-15T14:09:40.981Z" } }, { "type": "social_link", "id": "c401d53e-ca36-47e7-a861-83443599eb4c", "attributes": { "url": "https://linkedin.com/in/sophie-martin", "platform": "linkedin", "created_at": "2025-09-15T14:09:40.990Z" } }, { "type": "company", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77a", "attributes": { "name": "TechCorp Solutions", "description": "Leading technology consulting company", "workspace_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2025-09-15T14:09:40.995Z" } } ] } } } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/people/{id}": { "get": { "summary": "Get a specific person", "description": "Retrieve a single person by ID with related emails, phones, and social links", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the person to retrieve" } ], "responses": { "200": { "description": "Person retrieved successfully", "content": { "application/json": { "example": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-20T14:45:00Z" }, "relationships": { "emails": { "data": [ { "type": "emails", "id": "550e8400-e29b-41d4-a716-446655440002" } ] }, "phones": { "data": [ { "type": "phones", "id": "550e8400-e29b-41d4-a716-446655440003" } ] }, "companies": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440001" } ] } } }, "included": [ { "type": "emails", "id": "550e8400-e29b-41d4-a716-446655440002", "attributes": { "email": "john.doe@example.com", "type": "work" } }, { "type": "phones", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "phone": "+1-555-123-4567", "type": "mobile" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "Tech Solutions Inc.", "description": "Leading technology solutions provider", "workspace_id": "550e8400-e29b-41d4-a716-446655440004" } } ] }, "schema": { "$ref": "#/components/schemas/PeopleResponse" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } }, "patch": { "summary": "Update a person", "description": "Update an existing person record", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the person to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "attributes": { "$ref": "#/components/schemas/PeoplePutAttributes" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "Person updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/PeopleResponse" } } } } } } } }, "400": { "description": "Bad request - invalid data" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Person not found" } } }, "delete": { "summary": "Delete a person", "description": "Delete a person record", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the person to delete" } ], "responses": { "204": { "description": "Person deleted successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } } }, "/v1/people/{peopleId}/relationships/companies": { "post": { "summary": "Link companies to a person", "description": "Link existing companies to a person", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "peopleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the person to link companies to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleRelationshipsCompaniesRequest" } } } }, "responses": { "200": { "description": "Companies successfully linked to person", "content": { "application/json": { "example": { "data": [ { "type": "company", "id": "8a4db4c2-bb41-4099-8240-4f2b0faf2c6e" } ], "included": [ { "type": "company", "id": "8a4db4c2-bb41-4099-8240-4f2b0faf2c6e", "attributes": { "name": "TechCorp Solutions", "description": "An innovative technology company focused on AI solutions", "created_at": "2025-08-04T07:39:06.956Z", "updated_at": null } } ] }, "schema": { "$ref": "#/components/schemas/PeopleRelationshipsCompaniesResponse" } } } }, "400": { "description": "Bad request - invalid data or invalid company IDs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } } }, "/v1/connectors": { "post": { "operationId": "createConnector", "summary": "Create a new connector", "description": "Create a new connector record with integration details, configuration, and various relationships including published by workspace and media assets.", "tags": [ "Connectors" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorPost" }, "example": { "type": "connector", "attributes": { "slug": "salesforce", "name": "Salesforce", "description": "Connects to Salesforce CRM for sync.", "category": "api", "direction": "import", "tags": [ "crm", "cloud", "sync" ], "version": "2.1.0", "data_quality": { "imported_fields": [ "invoice", "company", "people" ], "last_synced": "2025-06-20T09:00:00Z" }, "redirect_url": "https://app.well.com/connectors/salesforce/success", "state": "active" }, "relationships": { "published_by": { "data": { "type": "workspace", "id": "airbyte" } }, "logo": { "data": { "type": "media", "id": "media3" } } }, "included": [ { "type": "workspace", "id": "airbyte", "attributes": { "name": "Airbyte", "description": "Open-source data integration platform", "website": "https://airbyte.com", "external_workspace_id": "airbyte_workspace_001" } }, { "type": "media", "id": "media3", "attributes": { "file_name": "salesforce_logo.png", "content_type": "image/png", "file_size": 15420, "media_type": "logo", "upload_url": "https://storage.well.com/media/salesforce_logo.png" } } ] } } } }, "responses": { "201": { "description": "Connector created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorPostResponse" }, "example": { "data": { "type": "connector", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "attributes": { "slug": "salesforce", "name": "Salesforce", "description": "Connects to Salesforce CRM for sync.", "category": "api", "direction": "import", "tags": [ "crm", "cloud", "sync" ], "status": "active", "data_quality": { "imported_fields": [ "invoice", "company", "people" ], "last_synced": "2025-06-20T09:00:00Z" }, "redirect_url": "https://app.well.com/connectors/salesforce/success", "state": "active", "created_at": "2025-10-07T14:30:00.000Z", "updated_at": "2025-10-07T14:30:00.000Z" }, "relationships": { "published_by": { "data": { "type": "workspace", "id": "airbyte" } }, "logo": { "data": { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010" } } } }, "included": [ { "type": "workspace", "id": "airbyte", "attributes": { "name": "Airbyte", "description": "Open-source data integration platform", "website": "https://airbyte.com" } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "salesforce_logo.png", "content_type": "image/png", "file_size": 12345 } } ] } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "missing_required_field": { "summary": "Missing required name", "value": { "code": "VALIDATION_ERROR", "status": 400, "title": "Validation Error", "message": "The name field is required", "meta": { "log_id": "550e8400-e29b-41d4-a716-446655440999", "errors": [ { "field": "name", "code": "REQUIRED", "message": "This field is required" } ] } } }, "invalid_category": { "summary": "Invalid category value", "value": { "code": "VALIDATION_ERROR", "status": 400, "title": "Validation Error", "message": "Invalid category value provided", "meta": { "log_id": "550e8400-e29b-41d4-a716-446655440998", "errors": [ { "field": "category", "code": "INVALID_ENUM", "message": "Category must be one of the allowed values" } ] } } } } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "get": { "operationId": "listConnectors", "summary": "List connectors", "description": "Retrieve a list of connector records with advanced filtering, sorting, and include capabilities. This endpoint supports:\n\n**Default behavior**: Returns all connectors associated with the workspace_id and organization extracted from the authentication token.\n\n**Include functionality**: Use the `include` parameter to get full details of related resources in the response.\n\n**Date filtering**: Filter by creation or update date ranges using `created_at_from/to` and `updated_at_from/to`.\n\n**Relationship filtering**: Filter by related entities using `workspace_id`, `published_by`, etc.\n\n**Category filtering**: Filter by connector categories like `crm`, `api`, `database`, etc.\n\n**Status filtering**: Filter by connector status and data synchronization state.\n\n**Sorting**: Sort results by `created_at`, `updated_at`, `name`, or `category` in ascending or descending order.", "tags": [ "Connectors" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of related resources to include. Available options: published_by, logo, category", "example": "published_by,logo" }, { "name": "created_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter connectors created from this date (ISO 8601 format)", "example": "2025-01-01T00:00:00Z" }, { "name": "created_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter connectors created until this date (ISO 8601 format)", "example": "2025-12-31T23:59:59Z" }, { "name": "updated_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter connectors updated from this date (ISO 8601 format)", "example": "2025-01-01T00:00:00Z" }, { "name": "updated_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter connectors updated until this date (ISO 8601 format)", "example": "2025-12-31T23:59:59Z" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by workspace ID that published the connector", "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "published_by", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by workspace that published the connector", "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "database", "data_warehouse", "other" ] }, "description": "Filter by connector category. See [all available categories](/enums/category-connector) for complete list.", "example": "crm" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "import", "export", "both" ] }, "description": "Filter by data flow direction capability", "example": "import" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "pending", "deprecated" ] }, "description": "Filter by connector status", "example": "active" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by connector name (partial match, case-insensitive)", "example": "Salesforce" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "name", "-name", "category", "-category" ] }, "description": "Sort by field. Use '-' prefix for descending order (e.g., '-created_at' for newest first)", "example": "-created_at" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Number of results to return per page", "example": 25 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination", "example": 1 } ], "responses": { "200": { "description": "Connectors retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorListResponse" }, "example": { "data": [ { "type": "connector", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "attributes": { "slug": "salesforce", "name": "Salesforce", "description": "Connects to Salesforce CRM for sync.", "category": "crm", "direction": "import", "tags": [ "crm", "cloud", "sync" ], "status": "active", "version": "2.1.0", "data_quality": { "imported_fields": [ "invoice", "company", "people" ], "last_synced": "2025-06-20T09:00:00Z" }, "redirect_url": "https://app.well.com/connectors/salesforce/success", "state": "active", "created_at": "2025-10-07T14:30:00.000Z", "updated_at": "2025-10-07T14:30:00.000Z" }, "relationships": { "published_by": { "data": { "type": "organization", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "logo": { "data": { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440002" } } } }, { "type": "connector", "id": "a1b2c3d4-58cc-4372-a567-0e02b2c3d480", "attributes": { "slug": "github", "name": "GitHub", "description": "Connects to GitHub for repository management and CI/CD.", "category": "ci_cd", "direction": "both", "tags": [ "git", "version-control", "ci-cd" ], "status": "active", "version": "1.5.2", "data_quality": { "imported_fields": [ "company", "people" ], "last_synced": "2025-06-19T15:30:00Z" }, "redirect_url": "https://app.well.com/connectors/github/success", "state": "active", "created_at": "2025-09-15T08:00:00.000Z", "updated_at": "2025-10-01T12:00:00.000Z" }, "relationships": { "published_by": { "data": { "type": "organization", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "logo": { "data": { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440003" } } } } ], "included": [ { "type": "organization", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "Well Technologies", "description": "Open-source data integration and financial technology platform", "website": "https://well.com", "external_id": "well_org_001" } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440002", "attributes": { "file_name": "salesforce_logo.png", "content_type": "image/png", "file_size": 15420, "media_type": "logo", "upload_url": "https://storage.well.com/media/salesforce_logo.png" } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "file_name": "github_logo.png", "content_type": "image/png", "file_size": 18750, "media_type": "logo", "upload_url": "https://storage.well.com/media/github_logo.png" } } ], "meta": { "page": 1, "limit": 25, "total": 2, "total_pages": 1 } } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/connectors/{id}": { "get": { "operationId": "getConnector", "summary": "Get connector by ID", "description": "Retrieve a specific connector by its unique identifier. This endpoint supports:\n\n**Include functionality**: Use the `include` parameter to get detailed relationship data including organization, category, and media information.\n\n**Relationship data**: Returns complete connector information with all attributes and relationships.", "tags": [ "Connectors" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the connector to retrieve", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "include", "in": "query", "required": false, "description": "Include related resources in the response. Multiple values can be comma-separated.", "schema": { "type": "string" }, "examples": { "single": { "value": "workspace", "description": "Include workspace information" }, "multiple": { "value": "workspace,category,media", "description": "Include workspace, category, and media information" } } } ], "responses": { "200": { "description": "Connector retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConnectorPostResponse" } }, "required": [ "data" ] }, "example": { "type": "connector", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "attributes": { "slug": "salesforce", "name": "Salesforce", "description": "Connects to Salesforce CRM for sync.", "category": "api", "direction": "import", "tags": [ "crm", "cloud", "sync" ], "status": "active", "version": "2.1.0", "data_quality": { "imported_fields": [ "invoice", "company", "people" ], "last_synced": "2025-06-20T09:00:00Z" }, "redirect_url": "https://app.well.com/connectors/salesforce/success", "state": "active", "created_at": "2025-10-07T14:30:00.000Z", "updated_at": "2025-10-07T14:30:00.000Z" }, "relationships": { "published_by": { "data": { "type": "workspace", "id": "airbyte" } }, "logo": { "data": { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010" } } }, "included": [ { "type": "workspace", "id": "airbyte", "attributes": { "name": "Airbyte", "description": "Open-source data integration platform", "website": "https://airbyte.com" } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "salesforce_logo.png", "content_type": "image/png", "file_size": 12345 } } ] } } } }, "400": { "description": "Bad request - invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "patch": { "operationId": "updateConnector", "summary": "Update an existing connector", "description": "Update a connector record with integration details, configuration, and various relationships. All fields are optional for partial updates.", "tags": [ "Connectors" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the connector to update", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorPatch" }, "example": { "type": "connector", "attributes": { "slug": "salesforce", "name": "Salesforce", "description": "Connects to Salesforce CRM for sync.", "category": "api", "direction": "import", "tags": [ "crm", "cloud", "sync" ], "data_quality": { "imported_fields": [ "invoice", "company", "people" ], "last_synced": "2025-06-20T09:00:00Z" }, "redirect_url": "https://app.well.com/connectors/salesforce/success", "state": "active" }, "relationships": { "published_by": { "data": { "type": "workspace", "id": "airbyte" } }, "logo": { "data": { "type": "media", "id": "media3" } } }, "included": [ { "type": "workspace", "id": "airbyte", "attributes": { "name": "Airbyte", "description": "Open-source data integration platform", "website": "https://airbyte.com", "external_workspace_id": "airbyte_workspace_001" } }, { "type": "media", "id": "media3", "attributes": { "file_name": "salesforce_logo.png", "content_type": "image/png", "file_size": 15420, "media_type": "logo", "upload_url": "https://storage.well.com/media/salesforce_logo.png" } } ] } } } }, "responses": { "200": { "description": "Connector updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorPostResponse" }, "example": { "data": { "type": "connector", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "attributes": { "slug": "salesforce", "name": "Salesforce", "description": "Connects to Salesforce CRM for sync.", "category": "api", "direction": "import", "tags": [ "crm", "cloud", "sync" ], "status": "active", "version": "2.1.0", "data_quality": { "imported_fields": [ "invoice", "company", "people" ], "last_synced": "2025-06-20T09:00:00Z" }, "redirect_url": "https://app.well.com/connectors/salesforce/success", "state": "active", "created_at": "2025-10-07T14:30:00.000Z", "updated_at": "2025-10-07T14:30:00.000Z" }, "relationships": { "published_by": { "data": { "type": "workspace", "id": "airbyte" } }, "logo": { "data": { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010" } } } }, "included": [ { "type": "workspace", "id": "airbyte", "attributes": { "name": "Airbyte", "description": "Open-source data integration platform", "website": "https://airbyte.com" } }, { "type": "media", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "file_name": "salesforce_logo.png", "content_type": "image/png", "file_size": 12345 } } ] } } } }, "400": { "description": "Bad request - invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "delete": { "operationId": "deleteConnector", "summary": "Delete a connector", "description": "Permanently delete a specific connector by its unique ID. This action is irreversible and will remove all associated connector data including configuration, relationships, and integration settings.", "tags": [ "Connectors" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the connector to delete", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "204": { "description": "Connector deleted successfully (no content returned)" }, "400": { "description": "Bad request - invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } } }, "/v1/transactions": { "post": { "summary": "Create Transaction", "description": "Create a new financial transaction record with comprehensive payment details, foreign exchange information, remittance data, fees, and relationship associations.", "operationId": "createTransaction", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPost" }, "example": { "type": "transaction", "attributes": { "scheme": "sepa", "external_ids": { "transaction_id": "TXN_SEPA_20240115_001", "payment_request_id": "PAY_REQ_001", "end_to_end_id": "E2E_20240115_ACME_001" }, "requested_execution_date": "2024-01-15", "executed_at": "2024-01-15T14:30:00Z", "booking_date": "2024-01-15", "value_date": "2024-01-15", "instructed_amount": { "currency": "EUR", "amount": 1250 }, "settlement_amount": { "currency": "USD", "amount": 1350.75 }, "foreign_exchange": { "currency_rate": "1.0806", "currency_pair": "EURUSD", "currency_rate_source": "ECB", "currency_rate_at": "2024-01-15T14:00:00Z" }, "transaction_type": "transfer", "status": "completed", "category_purpose": "CBFF", "purpose_code": "SALA", "remittance_information": { "unstructured": "Salary payment January 2024", "structured_reference": "RF18539007547034", "reference_type": "SCOR" }, "fees": [ { "type": "transfer_fee", "amount": 2.5, "currency": "EUR" }, { "type": "exchange_fee", "amount": 5, "currency": "EUR" } ] }, "relationships": { "debtor_payment_means": { "data": { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440000" } }, "creditor_payment_means": { "data": { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "debtor": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440002" } }, "creditor": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "documents": { "data": [ { "type": "invoice", "id": "550e8400-e29b-41d4-a716-446655440004" } ] }, "created_by": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440005" } }, "workspaces": { "data": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440006" } ] } } } } } }, "responses": { "201": { "description": "Transaction created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "example": { "data": { "type": "transaction", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "scheme": "sepa", "external_ids": { "transaction_id": "TXN_SEPA_20240115_001", "payment_request_id": "PAY_REQ_001", "end_to_end_id": "E2E_20240115_ACME_001" }, "requested_execution_date": "2024-01-15", "executed_at": "2024-01-15T14:30:00Z", "booking_date": "2024-01-15", "value_date": "2024-01-15", "instructed_amount": { "currency": "EUR", "amount": 1250 }, "settlement_amount": { "currency": "USD", "amount": 1350.75 }, "foreign_exchange": { "currency_rate": "1.0806", "currency_pair": "EURUSD", "currency_rate_source": "ECB", "currency_rate_at": "2024-01-15T14:00:00Z" }, "transaction_type": "transfer", "status": "completed", "category_purpose": "CBFF", "purpose_code": "SALA", "remittance_information": { "unstructured": "Salary payment January 2024", "structured_reference": "RF18539007547034", "reference_type": "SCOR" }, "fees": [ { "type": "transfer_fee", "amount": 2.5, "currency": "EUR" }, { "type": "exchange_fee", "amount": 5, "currency": "EUR" } ], "created_at": "2024-01-15T14:30:00Z", "updated_at": "2024-01-15T14:30:00Z" }, "relationships": { "debtor_payment_means": { "data": { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440000" } }, "creditor_payment_means": { "data": { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "debtor": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440002" } }, "creditor": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "documents": { "data": [ { "type": "invoice", "id": "550e8400-e29b-41d4-a716-446655440004" } ] }, "created_by": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440005" } }, "workspaces": { "data": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440006" } ] } } }, "included": [ { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "type": "account_details", "status": "active", "nickname": "Debtor Business Account", "description": "Primary SEPA account for outgoing payments" } }, { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "type": "account_details", "status": "active", "nickname": "Creditor Salary Account", "description": "Employee salary receiving account" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440002", "attributes": { "name": "Acme Corporation", "description": "Leading technology solutions provider (debtor)" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "first_name": "John", "last_name": "Doe", "job_title": "Software Engineer" } }, { "type": "invoice", "id": "550e8400-e29b-41d4-a716-446655440004", "attributes": { "invoice_number": "INV-2024-0115", "amount": 1250, "currency": "EUR" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440005", "attributes": { "first_name": "Marie", "last_name": "Martin", "job_title": "Finance Manager" } }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440006", "attributes": { "name": "Finance Operations", "description": "Financial operations and treasury management" } } ] } } } }, "400": { "description": "Bad Request - Invalid transaction data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "invalid_amount", "status": "400", "code": "INVALID_AMOUNT", "title": "Invalid Amount", "detail": "Transaction amount must be positive and cannot exceed limits", "source": { "pointer": "/data/attributes/instructed_amount/amount" } } ] } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "unauthorized", "status": "401", "code": "UNAUTHORIZED", "title": "Unauthorized", "detail": "Valid authentication credentials are required" } ] } } } } } }, "get": { "operationId": "listTransactions", "summary": "List Transactions", "description": "Workspace-scoped, cursor-paginated list of `transaction` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of transaction records.", "content": { "application/json": { "example": { "data": [ { "type": "transaction", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/transactions/{id}": { "delete": { "operationId": "deleteTransaction", "summary": "Delete a transaction", "description": "Delete a specific transaction by its unique ID or perform a soft delete based on business rules.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the transaction to delete", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440010" }, { "name": "force", "in": "query", "required": false, "description": "Force hard delete even for completed transactions (admin only)", "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "204": { "description": "Transaction deleted successfully", "headers": { "X-Deletion-Type": { "description": "Type of deletion performed (hard or soft)", "schema": { "type": "string", "enum": [ "hard", "soft" ] } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "unauthorized", "status": "401", "code": "UNAUTHORIZED", "title": "Unauthorized", "detail": "Valid authentication credentials are required" } ] } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "transaction_not_found", "status": "404", "code": "TRANSACTION_NOT_FOUND", "title": "Transaction Not Found", "detail": "The requested transaction does not exist or you don't have permission to access it", "source": { "parameter": "id" } } ] } } } } } }, "patch": { "operationId": "updateTransaction", "summary": "Update an existing transaction", "description": "Update a financial transaction record with comprehensive payment details, foreign exchange information, remittance data, fees, and relationship associations. This endpoint supports:\n\n**Partial updates**: All fields are optional - only provide the fields you want to update.\n\n**Status management**: Update transaction status from pending to completed, failed, or cancelled.\n\n**Relationship updates**: Modify debtor/creditor payment means, entities, documents, and workspace associations.\n\n**Financial adjustments**: Update amounts, foreign exchange rates, fees, and remittance information.\n\n**Audit trail**: Automatically updates the `updated_at` timestamp while preserving creation history.\n\n**Data integrity**: Validates business rules and maintains consistency across related entities.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the transaction to update", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440010" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPatch" }, "example": { "type": "transaction", "attributes": { "status": "completed", "executed_at": "2024-01-15T14:35:00Z", "booking_date": "2024-01-15", "value_date": "2024-01-15", "settlement_amount": { "currency": "USD", "amount": 1355.25 }, "foreign_exchange": { "currency_rate": "1.0842", "currency_rate_source": "ECB", "currency_rate_at": "2024-01-15T14:35:00Z" }, "remittance_information": { "unstructured": "Salary payment January 2024 - Updated", "structured_reference": "RF18539007547034", "reference_type": "SCOR" }, "fees": [ { "type": "transfer_fee", "amount": 2.5, "currency": "EUR" }, { "type": "exchange_fee", "amount": 7.5, "currency": "EUR" } ] }, "relationships": { "documents": { "data": [ { "type": "invoice", "id": "550e8400-e29b-41d4-a716-446655440004" }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440020" } ] } } } } } }, "responses": { "200": { "description": "Transaction updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "example": { "data": { "type": "transaction", "id": "550e8400-e29b-41d4-a716-446655440010", "attributes": { "scheme": "sepa", "external_ids": { "transaction_id": "TXN_SEPA_20240115_001", "payment_request_id": "PAY_REQ_001", "end_to_end_id": "E2E_20240115_ACME_001" }, "requested_execution_date": "2024-01-15", "executed_at": "2024-01-15T14:35:00Z", "booking_date": "2024-01-15", "value_date": "2024-01-15", "instructed_amount": { "currency": "EUR", "amount": 1250 }, "settlement_amount": { "currency": "USD", "amount": 1355.25 }, "foreign_exchange": { "currency_rate": "1.0842", "currency_pair": "EURUSD", "currency_rate_source": "ECB", "currency_rate_at": "2024-01-15T14:35:00Z" }, "transaction_type": "transfer", "status": "completed", "category_purpose": "CBFF", "purpose_code": "SALA", "remittance_information": { "unstructured": "Salary payment January 2024 - Updated", "structured_reference": "RF18539007547034", "reference_type": "SCOR" }, "fees": [ { "type": "transfer_fee", "amount": 2.5, "currency": "EUR" }, { "type": "exchange_fee", "amount": 7.5, "currency": "EUR" } ], "created_at": "2024-01-15T14:30:00Z", "updated_at": "2024-01-15T14:40:00Z" }, "relationships": { "debtor_payment_means": { "data": { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440000" } }, "creditor_payment_means": { "data": { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "debtor": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440002" } }, "creditor": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "documents": { "data": [ { "type": "invoice", "id": "550e8400-e29b-41d4-a716-446655440004" }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440020" } ] }, "created_by": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440005" } }, "workspaces": { "data": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440006" } ] } } }, "included": [ { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "type": "account_details", "status": "active", "nickname": "Business Primary Account", "description": "Main SEPA account for outgoing payments" } }, { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "type": "account_details", "status": "active", "nickname": "Employee Salary Account", "description": "Dedicated account for receiving salary payments" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440002", "attributes": { "name": "Acme Corporation", "description": "Leading technology solutions provider" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "job_title": "Software Engineer" } }, { "type": "invoice", "id": "550e8400-e29b-41d4-a716-446655440004", "attributes": { "invoice_number": "INV-2024-0115", "amount": 1250, "currency": "EUR", "status": "paid" } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440020", "attributes": { "name": "Payment Receipt", "filename": "receipt-2024-0115.pdf", "content_type": "application/pdf" } } ] } } } }, "400": { "description": "Bad request - invalid transaction data or ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "invalid_status_transition", "status": "400", "code": "INVALID_STATUS_TRANSITION", "title": "Invalid Status Transition", "detail": "Cannot change transaction status from 'completed' to 'pending'", "source": { "pointer": "/data/attributes/status" } } ] } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "unauthorized", "status": "401", "code": "UNAUTHORIZED", "title": "Unauthorized", "detail": "Valid authentication credentials are required" } ] } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "transaction_not_found", "status": "404", "code": "TRANSACTION_NOT_FOUND", "title": "Transaction Not Found", "detail": "The requested transaction does not exist or you don't have permission to access it", "source": { "parameter": "id" } } ] } } } } } }, "get": { "operationId": "getTransactions", "summary": "Get transaction", "description": "Fetch one `transaction` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The transaction record.", "content": { "application/json": { "example": { "data": { "type": "transaction", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "transaction not found / not in workspace scope." } } } }, "/v1/payment-means": { "post": { "operationId": "createPaymentMeans", "summary": "Create a new payment means", "description": "Create a new payment method or account for financial transactions. This endpoint supports various payment means types including bank accounts (IBAN/SWIFT), credit/debit cards, digital wallets, and other payment instruments.", "tags": [ "Payment Means" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMeansPost" }, "examples": { "us_bank_account": { "summary": "US Bank Account (ACH) - Complete Example", "value": { "type": "payment_means", "attributes": { "type": "account_details", "scheme": "ACH", "status": "active", "account_details": { "account_number": "1234567890", "routing_number": "021000021", "account_type": "checking", "currency": "USD" }, "bank_details": { "bank_name": "JPMorgan Chase Bank, N.A.", "bank_code": "CHASUS33", "branch_name": "New York Main Branch", "branch_code": "NY001" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared" }, "nickname": "US Operating Account", "description": "Primary USD account for US operations", "tags": [ "usd", "operating", "us", "primary" ] }, "relationships": { "holder": { "data": { "type": "company", "id": "holder-company-1" } }, "account_location": { "data": { "type": "location", "id": "bank-location-1" } }, "holder_location": { "data": { "type": "location", "id": "holder-location-1" } }, "bank": { "data": { "type": "company", "id": "bank-company-1" } }, "intermediary_banks": { "data": [ { "type": "company", "id": "intermediary-bank-1" } ] }, "ultimate_beneficiary": { "data": { "type": "people", "id": "beneficiary-person-1" } }, "created_by": { "data": { "type": "people", "id": "creator-person-1" } }, "documents": { "data": [ { "type": "document", "id": "bank-statement-1" }, { "type": "document", "id": "verification-letter-1" } ] }, "transactions": { "data": [ { "type": "transaction", "id": "recent-transaction-1" } ] }, "linked_payment_means": { "data": [ { "type": "payment_means", "id": "corporate-card-1" } ] } }, "included": [ { "type": "company", "id": "holder-company-1", "attributes": { "name": "ACME Corporation", "description": "Technology solutions provider", "registration": { "registered_name": "ACME Corporation Inc.", "trade_name": "ACME" }, "tax_id": { "value": "12-3456789", "type": "EIN" } } }, { "type": "location", "id": "bank-location-1", "attributes": { "street": "270 Park Avenue", "city": "New York", "state": "NY", "postal_code": "10017", "country": "US", "is_primary": true } }, { "type": "location", "id": "holder-location-1", "attributes": { "street": "123 Business Avenue", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US", "is_primary": true } }, { "type": "company", "id": "bank-company-1", "attributes": { "name": "JPMorgan Chase Bank", "description": "Major US financial institution", "registration": { "registered_name": "JPMorgan Chase Bank, N.A." }, "tax_id": { "value": "13-2624428", "type": "EIN" } } }, { "type": "company", "id": "intermediary-bank-1", "attributes": { "name": "Wells Fargo Bank", "description": "Intermediary bank for routing", "registration": { "registered_name": "Wells Fargo Bank, N.A." } } }, { "type": "people", "id": "beneficiary-person-1", "attributes": { "first_name": "Jane", "last_name": "Doe", "full_name": "Jane Doe", "date_of_birth": "1980-05-15" } }, { "type": "people", "id": "creator-person-1", "attributes": { "first_name": "John", "last_name": "Smith", "full_name": "John Smith" } }, { "type": "document", "id": "bank-statement-1", "attributes": { "name": "Bank Statement January 2025.pdf", "file_size": 245678, "content_type": "application/pdf" } }, { "type": "document", "id": "verification-letter-1", "attributes": { "name": "Account Verification Letter.pdf", "file_size": 123456, "content_type": "application/pdf" } }, { "type": "transaction", "id": "recent-transaction-1", "attributes": { "amount": { "value": 5000, "currency": "USD" }, "description": "Monthly supplier payment", "transaction_date": "2025-01-15T00:00:00.000Z", "status": "completed" } }, { "type": "payment_means", "id": "corporate-card-1", "attributes": { "type": "card", "nickname": "Corporate Visa Card", "scheme": "visa", "status": "active", "card_details": { "last_four": "1234", "expiry_month": 12, "expiry_year": 2026, "cardholder_name": "ACME CORPORATION" } } } ] } } } } } }, "responses": { "201": { "description": "Payment means created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMeansPostResponse" }, "example": { "data": { "type": "payment_means", "id": "pm-550e8400-e29b-41d4-a716-446655440099", "attributes": { "type": "account_details", "scheme": "ACH", "status": "active", "account_details": { "account_number": "1234567890", "routing_number": "021000021", "account_type": "checking", "currency": "USD" }, "bank_details": { "bank_name": "JPMorgan Chase Bank, N.A.", "bank_code": "CHASUS33", "branch_name": "New York Main Branch", "branch_code": "NY001" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared", "sanctions_check": "passed", "last_compliance_check": "2025-01-15T10:00:00.000Z" }, "metadata": { "source": "api", "external_id": null, "last_used_at": null, "usage_count": 0 }, "nickname": "US Operating Account", "description": "Primary USD account for US operations", "tags": [ "usd", "operating", "us", "primary" ], "is_primary": true, "is_verified": true, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" }, "relationships": { "holder": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "account_location": { "data": { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440101" } }, "holder_location": { "data": { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440102" } }, "bank": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440103" } }, "intermediary_banks": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440104" } ] }, "ultimate_beneficiary": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440201" } }, "created_by": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440202" } }, "documents": { "data": [ { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440301" }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440302" } ] }, "transactions": { "data": [ { "type": "transaction", "id": "550e8400-e29b-41d4-a716-446655440401" } ] }, "linked_payment_means": { "data": [ { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440501" } ] } }, "included": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "ACME Corporation", "description": "Technology solutions provider", "registration": { "registered_name": "ACME Corporation Inc.", "trade_name": "ACME" }, "tax_id": { "value": "12-3456789", "type": "EIN" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440101", "attributes": { "street": "270 Park Avenue", "city": "New York", "state": "NY", "postal_code": "10017", "country": "US", "is_primary": true, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440102", "attributes": { "street": "123 Business Avenue", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US", "is_primary": true, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440103", "attributes": { "name": "JPMorgan Chase Bank", "description": "Major US financial institution", "registration": { "registered_name": "JPMorgan Chase Bank, N.A." }, "tax_id": { "value": "13-2624428", "type": "EIN" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440104", "attributes": { "name": "Wells Fargo Bank", "description": "Intermediary bank for routing", "registration": { "registered_name": "Wells Fargo Bank, N.A." }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440201", "attributes": { "first_name": "Jane", "last_name": "Doe", "full_name": "Jane Doe", "date_of_birth": "1980-05-15", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440202", "attributes": { "first_name": "John", "last_name": "Smith", "full_name": "John Smith", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440301", "attributes": { "name": "Bank Statement January 2025.pdf", "file_size": 245678, "content_type": "application/pdf", "created_at": "2025-01-15T09:00:00.000Z", "updated_at": "2025-01-15T09:00:00.000Z" } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440302", "attributes": { "name": "Account Verification Letter.pdf", "file_size": 123456, "content_type": "application/pdf", "created_at": "2025-01-15T09:30:00.000Z", "updated_at": "2025-01-15T09:30:00.000Z" } }, { "type": "transaction", "id": "550e8400-e29b-41d4-a716-446655440401", "attributes": { "amount": { "value": 5000, "currency": "USD" }, "description": "Monthly supplier payment", "transaction_date": "2025-01-15T00:00:00.000Z", "status": "completed", "created_at": "2025-01-15T08:00:00.000Z", "updated_at": "2025-01-15T08:30:00.000Z" } }, { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440501", "attributes": { "type": "card", "scheme": "visa", "status": "active", "card_details": { "last_four": "1234", "expiry_month": 12, "expiry_year": 2026, "cardholder_name": "ACME CORPORATION", "nickname": "Corporate Visa Card", "is_primary": false, "created_at": "2024-06-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } } } ] } } } } }, "400": { "description": "Bad request - invalid payment means data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "unauthorized", "status": "401", "code": "UNAUTHORIZED", "title": "Unauthorized", "detail": "Valid authentication credentials are required" } ] } } } }, "404": { "description": "Not found - related entity does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "holder_not_found", "status": "404", "code": "HOLDER_NOT_FOUND", "title": "Holder Not Found", "detail": "The specified holder company or person does not exist", "source": { "pointer": "/data/relationships/holder/data/id" } } ] } } } } } }, "get": { "operationId": "listPaymentMeans", "summary": "List Payment Means", "description": "Workspace-scoped, cursor-paginated list of `payment_means` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of payment_means records.", "content": { "application/json": { "example": { "data": [ { "type": "payment_means", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/payment-means/{id}": { "delete": { "operationId": "deletePaymentMeans", "summary": "Delete a payment means", "description": "Delete a specific payment method or account by its unique ID.", "tags": [ "Payment Means" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the payment means to delete", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440010" } ], "responses": { "204": { "description": "Payment means deleted successfully", "headers": { "X-Deletion-Type": { "description": "Type of deletion performed (soft or hard)", "schema": { "type": "string", "enum": [ "soft", "hard" ] } }, "X-Deleted-At": { "description": "Timestamp when the payment means was deleted", "schema": { "type": "string", "format": "date-time" } } } }, "400": { "description": "Bad request - invalid payment means ID or deletion not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment means not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updatePaymentMeans", "summary": "Update an existing payment means", "description": "Update an existing payment method or account for financial transactions. This endpoint supports partial updates to payment means including bank accounts (IBAN/SWIFT), credit/debit cards, digital wallets, and other payment instruments.", "tags": [ "Payment Means" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMeansPatch" }, "examples": { "bank_account_sepa": { "summary": "SEPA Bank Account", "value": { "type": "payment_means", "attributes": { "type": "account_details", "scheme": "SEPA", "status": "active", "account_details": { "iban": "FR7612345678901234567890123", "bic": "BNPAFRPP", "currency": "EUR" }, "bank_details": { "bank_name": "BNP Paribas", "bank_code": "BNPA", "branch_name": "Paris Central", "branch_code": "001" }, "nickname": "Main Business Account", "description": "Primary operating account for SEPA payments", "tags": [ "business", "primary", "eur" ], "is_primary": true }, "relationships": { "holder": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440000" } }, "account_location": { "data": { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "holder_location": { "data": { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440002" } } } } }, "credit_card": { "summary": "Credit Card", "value": { "data": { "type": "payment_means", "attributes": { "type": "card_details", "scheme": "VISA", "status": "active", "card_details": { "masked_pan": "****-****-****-1234", "brand": "visa", "card_type": "credit", "expiry_month": 12, "expiry_year": 2027, "cardholder_name": "John Doe" }, "nickname": "Corporate Credit Card", "description": "Main corporate card for business expenses", "tags": [ "corporate", "expenses" ], "is_primary": false }, "relationships": { "holder": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "holder_location": { "data": { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440004" } } } } } }, "digital_wallet": { "summary": "Digital Wallet (PayPal)", "value": { "data": { "type": "payment_means", "attributes": { "type": "wallet_details", "scheme": "PAYPAL", "status": "active", "digital_wallet": { "provider": "paypal", "wallet_id": "user@example.com", "wallet_type": "business" }, "nickname": "Business PayPal", "description": "PayPal account for online payments", "tags": [ "online", "paypal" ], "is_primary": false }, "relationships": { "holder": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440005" } } } } } }, "us_bank_account": { "summary": "US Bank Account (ACH) - Complete Example", "value": { "data": { "type": "payment_means", "attributes": { "type": "account_details", "scheme": "ACH", "status": "active", "account_details": { "account_number": "1234567890", "routing_number": "021000021", "account_type": "checking", "currency": "USD" }, "bank_details": { "bank_name": "JPMorgan Chase Bank, N.A.", "bank_code": "CHASUS33", "branch_name": "New York Main Branch", "branch_code": "NY001" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared" }, "nickname": "US Operating Account", "description": "Primary USD account for US operations", "tags": [ "usd", "operating", "us", "primary" ] }, "relationships": { "holder": { "data": { "type": "company", "id": "holder-company-1" } }, "account_location": { "data": { "type": "location", "id": "bank-location-1" } }, "holder_location": { "data": { "type": "location", "id": "holder-location-1" } }, "bank": { "data": { "type": "company", "id": "bank-company-1" } }, "intermediary_banks": { "data": [ { "type": "company", "id": "intermediary-bank-1" } ] }, "ultimate_beneficiary": { "data": { "type": "people", "id": "beneficiary-person-1" } }, "created_by": { "data": { "type": "people", "id": "creator-person-1" } }, "documents": { "data": [ { "type": "document", "id": "bank-statement-1" }, { "type": "document", "id": "verification-letter-1" } ] }, "transactions": { "data": [ { "type": "transaction", "id": "recent-transaction-1" } ] }, "linked_payment_means": { "data": [ { "type": "payment_means", "id": "corporate-card-1" } ] } }, "included": [ { "type": "company", "id": "holder-company-1", "attributes": { "name": "ACME Corporation", "description": "Technology solutions provider", "registration": { "registered_name": "ACME Corporation Inc.", "trade_name": "ACME" }, "tax_id": { "value": "12-3456789", "type": "EIN" } } }, { "type": "location", "id": "bank-location-1", "attributes": { "street": "270 Park Avenue", "city": "New York", "state": "NY", "postal_code": "10017", "country": "US", "is_primary": true } }, { "type": "location", "id": "holder-location-1", "attributes": { "street": "123 Business Avenue", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US", "is_primary": true } }, { "type": "company", "id": "bank-company-1", "attributes": { "name": "JPMorgan Chase Bank", "description": "Major US financial institution", "registration": { "registered_name": "JPMorgan Chase Bank, N.A." }, "tax_id": { "value": "13-2624428", "type": "EIN" } } }, { "type": "company", "id": "intermediary-bank-1", "attributes": { "name": "Wells Fargo Bank", "description": "Intermediary bank for routing", "registration": { "registered_name": "Wells Fargo Bank, N.A." } } }, { "type": "people", "id": "beneficiary-person-1", "attributes": { "first_name": "Jane", "last_name": "Doe", "full_name": "Jane Doe", "date_of_birth": "1980-05-15" } }, { "type": "people", "id": "creator-person-1", "attributes": { "first_name": "John", "last_name": "Smith", "full_name": "John Smith" } }, { "type": "document", "id": "bank-statement-1", "attributes": { "name": "Bank Statement January 2025.pdf", "file_size": 245678, "content_type": "application/pdf" } }, { "type": "document", "id": "verification-letter-1", "attributes": { "name": "Account Verification Letter.pdf", "file_size": 123456, "content_type": "application/pdf" } }, { "type": "transaction", "id": "recent-transaction-1", "attributes": { "amount": { "value": 5000, "currency": "USD" }, "description": "Monthly supplier payment", "transaction_date": "2025-01-15T00:00:00.000Z", "status": "completed" } }, { "type": "payment_means", "id": "corporate-card-1", "attributes": { "type": "card", "scheme": "visa", "status": "active", "card_details": { "last_four": "1234", "expiry_month": 12, "expiry_year": 2026, "cardholder_name": "ACME CORPORATION" }, "nickname": "Corporate Visa Card" } } ] } } } } } } }, "responses": { "201": { "description": "Payment means created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMeansPostResponse" }, "example": { "data": { "type": "payment_means", "id": "pm-550e8400-e29b-41d4-a716-446655440099", "attributes": { "type": "account_details", "scheme": "ACH", "status": "active", "account_details": { "account_number": "1234567890", "routing_number": "021000021", "account_type": "checking", "currency": "USD" }, "bank_details": { "bank_name": "JPMorgan Chase Bank, N.A.", "bank_code": "CHASUS33", "branch_name": "New York Main Branch", "branch_code": "NY001" }, "compliance": { "kyc_status": "verified", "aml_status": "cleared", "sanctions_check": "passed", "last_compliance_check": "2025-01-15T10:00:00.000Z" }, "metadata": { "source": "api", "external_id": null, "last_used_at": null, "usage_count": 0 }, "nickname": "US Operating Account", "description": "Primary USD account for US operations", "tags": [ "usd", "operating", "us", "primary" ], "is_primary": true, "is_verified": true, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" }, "relationships": { "holder": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440001" } }, "account_location": { "data": { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440101" } }, "holder_location": { "data": { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440102" } }, "bank": { "data": { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440103" } }, "intermediary_banks": { "data": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440104" } ] }, "ultimate_beneficiary": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440201" } }, "created_by": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440202" } }, "documents": { "data": [ { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440301" }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440302" } ] }, "transactions": { "data": [ { "type": "transaction", "id": "550e8400-e29b-41d4-a716-446655440401" } ] }, "linked_payment_means": { "data": [ { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440501" } ] } }, "included": [ { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440001", "attributes": { "name": "ACME Corporation", "description": "Technology solutions provider", "registration": { "registered_name": "ACME Corporation Inc.", "trade_name": "ACME" }, "tax_id": { "value": "12-3456789", "type": "EIN" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440101", "attributes": { "street": "270 Park Avenue", "city": "New York", "state": "NY", "postal_code": "10017", "country": "US", "is_primary": true, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "location", "id": "550e8400-e29b-41d4-a716-446655440102", "attributes": { "street": "123 Business Avenue", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US", "is_primary": true, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440103", "attributes": { "name": "JPMorgan Chase Bank", "description": "Major US financial institution", "registration": { "registered_name": "JPMorgan Chase Bank, N.A." }, "tax_id": { "value": "13-2624428", "type": "EIN" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "company", "id": "550e8400-e29b-41d4-a716-446655440104", "attributes": { "name": "Wells Fargo Bank", "description": "Intermediary bank for routing", "registration": { "registered_name": "Wells Fargo Bank, N.A." }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440201", "attributes": { "first_name": "Jane", "last_name": "Doe", "full_name": "Jane Doe", "date_of_birth": "1980-05-15", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440202", "attributes": { "first_name": "John", "last_name": "Smith", "full_name": "John Smith", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440301", "attributes": { "name": "Bank Statement January 2025.pdf", "file_size": 245678, "content_type": "application/pdf", "created_at": "2025-01-15T09:00:00.000Z", "updated_at": "2025-01-15T09:00:00.000Z" } }, { "type": "document", "id": "550e8400-e29b-41d4-a716-446655440302", "attributes": { "name": "Account Verification Letter.pdf", "file_size": 123456, "content_type": "application/pdf", "created_at": "2025-01-15T09:30:00.000Z", "updated_at": "2025-01-15T09:30:00.000Z" } }, { "type": "transaction", "id": "550e8400-e29b-41d4-a716-446655440401", "attributes": { "amount": { "value": 5000, "currency": "USD" }, "description": "Monthly supplier payment", "transaction_date": "2025-01-15T00:00:00.000Z", "status": "completed", "created_at": "2025-01-15T08:00:00.000Z", "updated_at": "2025-01-15T08:30:00.000Z" } }, { "type": "payment_means", "id": "550e8400-e29b-41d4-a716-446655440501", "attributes": { "type": "card", "scheme": "visa", "status": "active", "card_details": { "last_four": "1234", "expiry_month": 12, "expiry_year": 2026, "cardholder_name": "ACME CORPORATION" }, "nickname": "Corporate Visa Card", "is_primary": false, "created_at": "2024-06-01T00:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } } ] } } } } }, "400": { "description": "Bad request - invalid payment means data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "unauthorized", "status": "401", "code": "UNAUTHORIZED", "title": "Unauthorized", "detail": "Valid authentication credentials are required" } ] } } } }, "404": { "description": "Not found - related entity does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "holder_not_found", "status": "404", "code": "HOLDER_NOT_FOUND", "title": "Holder Not Found", "detail": "The specified holder company or person does not exist", "source": { "pointer": "/data/relationships/holder/data/id" } } ] } } } } } }, "get": { "operationId": "getPaymentMeans", "summary": "Get payment means", "description": "Fetch one `payment_means` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The payment_means record.", "content": { "application/json": { "example": { "data": { "type": "payment_means", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "payment_means not found / not in workspace scope." } } } }, "/v1/emails": { "get": { "summary": "Get emails", "description": "Retrieve a list of email addresses with advanced filtering, sorting, and include capabilities. This endpoint supports:\n\n**Default behavior**: Returns email addresses with basic information (IDs only for relationships).\n\n**Trailing slashes**: Works with or without trailing slashes '/'.\n\n**Include functionality**: Use the `include` parameter to get detailed relationship data.\n\n**Date filtering**: Filter by creation, update, or deletion date ranges.\n\n**Relationship filtering**: Filter by related entities using various identifiers.\n\n**Contact filtering**: Filter by contact information and verification status.\n\n**Company filtering**: Filter by company registration details.\n\n**Email filtering**: Filter by primary status, verification, and label.\n\n**Sorting**: Sort results by date fields in ascending or descending order.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of related resources to include with detailed attributes. Available options: persons, companies, workspaces", "example": "persons,companies,workspaces" }, { "name": "created_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter emails created on or after this datetime (ISO 8601 format)", "example": "2023-01-01T00:00:00Z" }, { "name": "created_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter emails created on or before this datetime (ISO 8601 format)", "example": "2023-12-31T23:59:59Z" }, { "name": "updated_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter emails updated on or after this datetime (ISO 8601 format)" }, { "name": "updated_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter emails updated on or before this datetime (ISO 8601 format)" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter emails by workspace UUID" }, { "name": "external_workspace_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter emails by external workspace identifier" }, { "name": "people_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter emails by person UUID" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "format": "email" }, "description": "Filter by email address", "example": "user@example.com" }, { "name": "company_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by company ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "registration_tax_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by company registration tax ID", "example": "12345678901" }, { "name": "registration_registered_value", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by company registration registered value", "example": "123456789" }, { "name": "is_primary", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Filter by primary email status", "example": true }, { "name": "is_verified", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Filter by verification status", "example": true }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "work", "personal", "support", "billing", "other" ], "default": "work" }, "description": "Filter by email label", "example": "work" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "-created_at" ], "default": "-created_at" }, "description": "Sort emails by date fields. Prefix with '-' for descending order.", "example": "-created_at" }, { "name": "page[limit]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of emails to return per page (1-100)", "example": 25 }, { "name": "page[cursor]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for pagination to get the next page of results", "example": "eyJjcmVhdGVkX2F0IjoiMjAyMy0wNi0xNVQxMDozMDowMFoiLCJpZCI6InV1aWQtaGVyZSJ9" } ], "responses": { "200": { "description": "Emails retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGetResponse" }, "example": { "data": [ { "type": "email", "id": "email1-uuid", "attributes": { "value": "sarah.wilson@techcorp.com", "is_primary": true, "is_verified": true, "label": "work", "created_at": "2023-06-15T10:30:00Z", "updated_at": "2023-06-15T10:30:00Z" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "person1-uuid" } ] }, "companies": { "data": [ { "type": "company", "id": "company1-uuid" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace1-uuid" } ] } } } ], "included": [ { "type": "people", "id": "person1-uuid", "attributes": { "first_name": "Sarah", "last_name": "Wilson", "full_name": "Sarah Wilson", "created_at": "2023-06-15T09:00:00Z", "updated_at": "2023-06-15T09:00:00Z" } }, { "type": "company", "id": "company1-uuid", "attributes": { "name": "TechCorp Solutions", "description": "Leading technology company", "domain_name_primary_link_url": "techcorp.com", "locale": "en", "created_at": "2023-06-01T08:00:00Z", "updated_at": "2023-06-01T08:00:00Z" } }, { "type": "workspace", "id": "workspace1-uuid", "attributes": { "name": "Sales Team", "description": "Sales team workspace", "avatar_color": "#FF5733", "auto_extract_enabled": true, "created_at": "2023-06-01T08:00:00Z", "updated_at": "2023-06-01T08:00:00Z" } } ], "meta": { "total": 150, "page": 1, "limit": 20 } } } } }, "400": { "description": "Bad request - invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } }, "post": { "summary": "Create email", "description": "Create a new email address with relationships to people, companies, or workspaces", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCreateRequest" }, "example": { "attributes": { "value": "sarah.wilson@techcorp.com", "is_primary": true, "label": "work" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "people1" } ] }, "companies": { "data": [ { "type": "company", "id": "company_tenant" } ] }, "workspaces": { "data": [ { "type": "workspace", "external_workspace_id": "fygr_123" }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440000" } ] } } } } } }, "responses": { "201": { "description": "Email created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCreateResponse" }, "example": { "data": { "type": "email", "id": "email1-uuid", "attributes": { "value": "sarah.wilson@techcorp.com", "is_primary": true, "is_verified": true, "label": "work", "created_at": "2023-06-15T10:30:00Z", "updated_at": "2023-06-15T10:30:00Z" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "person1-uuid" } ] }, "companies": { "data": [ { "type": "company", "id": "company1-uuid" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace1-uuid" } ] } } }, "included": [ { "type": "people", "id": "person1-uuid", "attributes": { "first_name": "Sarah", "last_name": "Wilson", "full_name": "Sarah Wilson", "created_at": "2023-06-15T09:00:00Z", "updated_at": "2023-06-15T09:00:00Z" } }, { "type": "company", "id": "company1-uuid", "attributes": { "name": "TechCorp Solutions", "description": "Leading technology company", "domain_name_primary_link_url": "techcorp.com", "locale": "en", "created_at": "2023-06-01T08:00:00Z", "updated_at": "2023-06-01T08:00:00Z" } }, { "type": "workspace", "id": "workspace1-uuid", "attributes": { "name": "Sales Team", "description": "Sales team workspace", "avatar_color": "#FF5733", "auto_extract_enabled": true, "created_at": "2023-06-01T08:00:00Z", "updated_at": "2023-06-01T08:00:00Z" } } ] } } } }, "400": { "description": "Bad request - invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } } }, "/v1/phones": { "post": { "summary": "Create phone", "description": "Create a new phone number with relationships to people, companies, or workspaces", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneCreateRequest" }, "example": { "data": { "type": "phone", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "attributes": { "country_code": 1, "national_number": "4155552671", "e164_number": "+14155552671", "label": "work", "is_primary": true, "is_verified": true, "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "people1" } ] }, "companies": { "data": [ { "type": "company", "id": "company_tenant" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace_sales" }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440000" } ] } } }, "included": [ { "type": "people", "id": "people1", "attributes": { "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } }, { "type": "company", "id": "company_tenant", "attributes": { "name": "Acme Corporation", "description": "Leading technology company", "locale": "en", "domain_name_primary_link_url": "acme.com", "created_at": "2023-12-01T09:00:00Z", "updated_at": "2023-12-01T09:00:00Z" } }, { "type": "workspace", "id": "workspace_sales", "attributes": { "name": "Sales Team Workspace", "description": "Workspace for sales activities", "avatar_color": "#FF6B35", "external_workspace_id": "fygr_123", "auto_extract_enabled": true, "created_at": "2024-01-10T08:15:00Z", "updated_at": "2024-01-10T08:15:00Z" } }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "name": "Marketing Team Workspace", "description": "Workspace for marketing campaigns", "avatar_color": "#4A90E2", "external_workspace_id": "mkt_workspace_001", "auto_extract_enabled": false, "created_at": "2024-01-12T14:45:00Z", "updated_at": "2024-01-12T14:45:00Z" } } ] } } } }, "responses": { "201": { "description": "Phone created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneCreateResponse" }, "example": { "data": [ { "type": "phone", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "attributes": { "country_code": 1, "national_number": "4155552671", "e164_number": "+14155552671", "label": "work", "is_primary": true, "is_verified": true, "created_at": "2023-11-07T05:31:56Z" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "people1", "attributes": { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" } } ] }, "companies": { "data": [ { "type": "company", "id": "company_tenant", "attributes": { "name": "Acme Corporation", "description": "Leading technology company", "website": "https://acme.com" } } ] }, "workspaces": { "data": [ { "type": "workspace", "external_workspace_id": "fygr_123", "attributes": { "name": "Sales Team Workspace", "description": "Workspace for sales activities" } }, { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "name": "Marketing Team Workspace", "description": "Workspace for marketing campaigns" } } ] } } } ] } } } }, "400": { "description": "Bad request - invalid phone data or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } }, "get": { "operationId": "listPhones", "summary": "List Phones", "description": "Workspace-scoped, cursor-paginated list of `phone` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of phone records.", "content": { "application/json": { "example": { "data": [ { "type": "phone", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/phones/{id}": { "delete": { "summary": "Delete person phone", "description": "Remove a phone number from a person", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the phone number to delete" } ], "responses": { "204": { "description": "Person phone deleted successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } }, "get": { "operationId": "getPhones", "summary": "Get phone", "description": "Fetch one `phone` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The phone record.", "content": { "application/json": { "example": { "data": { "type": "phone", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "phone not found / not in workspace scope." } } } }, "/v1/people/{personId}/phones/{phoneId}/verify": { "post": { "summary": "Verify phone number", "description": "Send verification code by whatsapp to a phone number for verification", "tags": [ "Phone Verification" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the person" }, { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the phone to verify" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "UUID of the workspace. If not provided, the workspace from the bearer token will be used." } } } } } }, "responses": { "204": { "description": "Verification code sent successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } } }, "/v1/people/{personId}/phones/{phoneId}/verify/{code}": { "post": { "summary": "Create Phone Verification Code", "description": "Validate the verification code received by WhatsApp for a phone number. If the code is valid, sets the is_verify field to true for the person's phone.", "tags": [ "Phone Verification" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the person" }, { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the phone to verify" }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{6}$" }, "description": "6-digit verification code" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "UUID of the workspace. If not provided, the workspace from the bearer token will be used." } } } } } }, "responses": { "204": { "description": "Verification code created and validated successfully" }, "400": { "description": "Bad request - invalid verification code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/PersonNotFound" } } } }, "/v1/people/{personId}/phones/{phoneId}/{code}": { "post": { "summary": "Validate verification code", "description": "Validate the verification code sent to a phone number (the code have 5 minutes to be used)", "tags": [ "Phone Verification" ], "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the person" }, { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the phone to verify" }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{6}$" }, "description": "6-digit verification code" } ], "responses": { "204": { "description": "Verification code validated successfully" }, "400": { "description": "Bad request - invalid verification code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Person or phone not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/emails/{id}": { "get": { "summary": "Get email by ID", "description": "Retrieve a specific email by its UUID or email address with optional relationship details", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "uuid", "description": "UUID of the email to retrieve" }, { "type": "string", "format": "email", "description": "Email address to retrieve" } ] }, "description": "UUID or email address of the email to retrieve", "examples": { "uuid": { "value": "550e8400-e29b-41d4-a716-446655440000" }, "email": { "value": "user@example.com" } } } ], "responses": { "200": { "description": "Email retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailResponse" }, "example": { "data": { "type": "email", "id": "email1-uuid", "attributes": { "value": "sarah.wilson@techcorp.com", "is_primary": true, "is_verified": true, "label": "work", "created_at": "2023-06-15T10:30:00Z", "updated_at": "2023-06-15T10:30:00Z" }, "relationships": { "persons": { "data": [ { "type": "people", "id": "person1-uuid" } ] }, "companies": { "data": [ { "type": "company", "id": "company1-uuid" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "workspace1-uuid" } ] } } }, "included": [ { "type": "people", "id": "person1-uuid", "attributes": { "first_name": "Sarah", "last_name": "Wilson", "full_name": "Sarah Wilson", "created_at": "2023-06-15T09:00:00Z", "updated_at": "2023-06-15T09:00:00Z" } }, { "type": "company", "id": "company1-uuid", "attributes": { "name": "TechCorp Solutions", "description": "Leading technology company", "domain_name_primary_link_url": "techcorp.com", "locale": "en", "created_at": "2023-06-01T08:00:00Z", "updated_at": "2023-06-01T08:00:00Z" } }, { "type": "workspace", "id": "workspace1-uuid", "attributes": { "name": "Sales Team", "description": "Sales team workspace", "avatar_color": "#FF5733", "auto_extract_enabled": true, "created_at": "2023-06-01T08:00:00Z", "updated_at": "2023-06-01T08:00:00Z" } } ] } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Not found - related entity does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "holder_not_found", "status": "404", "code": "HOLDER_NOT_FOUND", "title": "Holder Not Found", "detail": "The specified holder company or person does not exist", "source": { "pointer": "/data/relationships/holder/data/id" } } ] } } } } } }, "delete": { "summary": "Delete email", "description": "Remove an email address from a person, company, or workspace", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "uuid", "description": "UUID of the email to delete" }, { "type": "string", "format": "email", "description": "Email address to delete" } ] }, "description": "UUID or email address of the email to delete", "examples": { "uuid": { "value": "550e8400-e29b-41d4-a716-446655440000" }, "email": { "value": "user@example.com" } } } ], "responses": { "204": { "description": "Email deleted successfully" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Not found - related entity does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "id": "holder_not_found", "status": "404", "code": "HOLDER_NOT_FOUND", "title": "Holder Not Found", "detail": "The specified holder company or person does not exist", "source": { "pointer": "/data/relationships/holder/data/id" } } ] } } } } } } }, "/v1/workspaces": { "post": { "summary": "Create workspace", "description": "Create a new workspace record", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "type": "workspace", "attributes": { "name": "Marketing Team Workspace", "description": "Collaborative workspace for the marketing team to manage campaigns and content", "avatar_color": "#FF5733", "external_workspace_id": "mkt-workspace-001", "auto_extract_enabled": false }, "relationships": { "owner": { "data": { "type": "people", "id": "temp-id1" } } }, "included": { "owner": { "data": { "type": "people", "id": "temp-id1", "attributes": { "first_name": "Sophie", "last_name": "Martin" } } } } }, "schema": { "$ref": "#/components/schemas/WorkspaceRequest" } } } }, "responses": { "201": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/workspaces/{id}": { "get": { "summary": "Get workspace", "description": "Retrieve a specific workspace by ID", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the workspace to retrieve" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of related resources to include. Available options: memberships" } ], "responses": { "200": { "description": "Workspace retrieved successfully", "content": { "application/json": { "example": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "name": "Marketing Team Workspace", "description": "Collaborative workspace for the marketing team to manage campaigns and content", "created_at": "2024-01-05T08:00:00Z", "updated_at": "2024-01-18T12:15:00Z", "avatar_color": "#FF5733", "external_workspace_id": "mkt-workspace-001", "auto_extract_enabled": false }, "relationships": { "memberships": { "data": [ { "type": "membership", "id": "550e8400-e29b-41d4-a716-446655440005" }, { "type": "membership", "id": "550e8400-e29b-41d4-a716-446655440006" } ] } } }, "included": [ { "type": "membership", "id": "550e8400-e29b-41d4-a716-446655440005", "attributes": { "role": "owner", "status": "active" } }, { "type": "memberships", "id": "550e8400-e29b-41d4-a716-446655440006", "attributes": { "role": "member", "status": "active" } } ] }, "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/WorkspaceNotFound" } } }, "patch": { "summary": "Update workspace", "description": "Update an existing workspace record", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the workspace to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacePutRequest" } } } }, "responses": { "200": { "description": "Workspace updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/WorkspaceNotFound" } } }, "delete": { "summary": "Delete workspace", "description": "Delete a workspace record", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the workspace to delete" } ], "responses": { "204": { "description": "Workspace deleted successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/WorkspaceNotFound" } } } }, "/v1/memberships": { "post": { "summary": "Create a new membership", "description": "Create a new membership linking a person to a workspace with a specific role", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "type": "membership", "attributes": { "role": "member" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "person": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000" } } } }, "schema": { "$ref": "#/components/schemas/MembershipCreateRequest" } } } }, "responses": { "201": { "description": "Membership created successfully", "content": { "application/json": { "example": { "data": { "type": "memberships", "id": "550e8400-e29b-41d4-a716-446655440007", "attributes": { "role": "member", "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:30:00Z" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "person": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000" } } } }, "included": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "name": "Marketing Team Workspace", "description": "Collaborative workspace for the marketing team to manage campaigns and content", "avatar_color": "#FF5733", "external_workspace_id": "mkt-workspace-001", "auto_extract_enabled": false, "created_at": "2024-01-05T08:00:00Z", "updated_at": "2024-01-18T12:15:00Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "first_name": "Sarah", "last_name": "Johnson", "full_name": "Sarah Johnson", "created_at": "2024-01-10T09:00:00Z", "updated_at": "2024-01-10T09:00:00Z" } } ] }, "schema": { "$ref": "#/components/schemas/MembershipGetResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/CompanyOrPersonNotFound" } } }, "get": { "summary": "Get memberships", "description": "Retrieve memberships with optional filtering by person", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "filter[person]", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter memberships by person ID" }, { "name": "page[number]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of items per page" } ], "responses": { "200": { "description": "Memberships retrieved successfully", "content": { "application/json": { "example": { "data": [ { "type": "memberships", "id": "550e8400-e29b-41d4-a716-446655440007", "attributes": { "role": "member", "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:30:00Z" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "person": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000" } } } } ], "included": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "name": "Marketing Team Workspace", "description": "Collaborative workspace for the marketing team to manage campaigns and content", "avatar_color": "#FF5733", "external_workspace_id": "mkt-workspace-001", "auto_extract_enabled": false, "created_at": "2024-01-05T08:00:00Z", "updated_at": "2024-01-18T12:15:00Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "first_name": "Sarah", "last_name": "Johnson", "full_name": "Sarah Johnson", "created_at": "2024-01-10T09:00:00Z", "updated_at": "2024-01-10T09:00:00Z" } } ], "meta": { "total": 1, "page": 1, "limit": 20, "total_pages": 1 } }, "schema": { "$ref": "#/components/schemas/MembershipListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/memberships/{id}": { "get": { "summary": "Get a specific membership", "description": "Retrieve a specific membership by ID", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the membership to retrieve" } ], "responses": { "200": { "description": "Membership retrieved successfully", "content": { "application/json": { "example": { "data": { "type": "memberships", "id": "550e8400-e29b-41d4-a716-446655440007", "attributes": { "role": "member", "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:30:00Z" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "person": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000" } } } }, "included": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "name": "Marketing Team Workspace", "description": "Collaborative workspace for the marketing team to manage campaigns and content", "avatar_color": "#FF5733", "external_workspace_id": "mkt-workspace-001", "auto_extract_enabled": false, "created_at": "2024-01-05T08:00:00Z", "updated_at": "2024-01-18T12:15:00Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "first_name": "Sarah", "last_name": "Johnson", "full_name": "Sarah Johnson", "created_at": "2024-01-10T09:00:00Z", "updated_at": "2024-01-10T09:00:00Z" } } ] }, "schema": { "$ref": "#/components/schemas/MembershipGetResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/MembershipNotFound" } } }, "patch": { "summary": "Update a membership", "description": "Update an existing membership role", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the membership to update" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "type": "membership", "attributes": { "role": "admin" } }, "schema": { "$ref": "#/components/schemas/MembershipUpdateRequest" } } } }, "responses": { "200": { "description": "Membership updated successfully", "content": { "application/json": { "example": { "data": { "type": "memberships", "id": "550e8400-e29b-41d4-a716-446655440007", "attributes": { "role": "member", "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:30:00Z" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003" } }, "person": { "data": { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000" } } } }, "included": [ { "type": "workspace", "id": "550e8400-e29b-41d4-a716-446655440003", "attributes": { "name": "Marketing Team Workspace", "description": "Collaborative workspace for the marketing team to manage campaigns and content", "avatar_color": "#FF5733", "external_workspace_id": "mkt-workspace-001", "auto_extract_enabled": false, "created_at": "2024-01-05T08:00:00Z", "updated_at": "2024-01-18T12:15:00Z" } }, { "type": "people", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "first_name": "Sarah", "last_name": "Johnson", "full_name": "Sarah Johnson", "created_at": "2024-01-10T09:00:00Z", "updated_at": "2024-01-10T09:00:00Z" } } ] }, "schema": { "$ref": "#/components/schemas/MembershipUpdateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/MembershipNotFound" } } }, "delete": { "summary": "Delete a membership", "description": "Remove a person from a workspace", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the membership to delete" } ], "responses": { "204": { "description": "Membership deleted successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/MembershipNotFound" } } } }, "/v1/medias": { "post": { "summary": "Create media", "description": "Create a new media record with relationships to people, companies, or workspaces", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MediaCreateRequestMultipart" }, "example": { "file": "@/path/to/image.jpg", "data": "{\"type\":\"media\",\"attributes\":{\"media_type\":\"avatar\",\"is_primary\":true},\"relationships\":{\"people\":{\"data\":[{\"type\":\"people\",\"id\":\"550e8400-e29b-41d4-a716-446655440000\"}]}}}" } }, "application/json": { "schema": { "$ref": "#/components/schemas/MediaPost" } } } }, "responses": { "201": { "description": "Media created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaCreateResponse" }, "example": { "data": [ { "type": "media", "id": "media1", "attributes": { "media_type": "avatar", "url": "https://cdn.example.com/avatar.jpg", "is_primary": true, "uploaded_at": "2025-06-01T10:00:00Z", "processed_at": "2025-06-01T10:00:00Z" }, "relationships": { "people": { "data": [ { "type": "people", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77c" } ] }, "companies": { "data": [ { "type": "company", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77a" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77b" } ] } }, "included": [ { "type": "people", "id": "people1", "attributes": { "first_name": "John", "last_name": "Doe", "job_title": "Software Engineer", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-06-01T10:00:00Z" } }, { "type": "company", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77a", "attributes": { "name": "Tech Startup Inc", "description": "An innovative technology company focused on AI and ML solutions", "registration_tax_id": "12345678901", "registration_registered_value": "123456789", "created_at": "2025-08-03T10:38:40.967Z", "updated_at": "2025-08-04T07:51:01.785Z" } }, { "type": "workspace", "id": "workspace_tenant", "attributes": { "name": "Marketing Team Workspace", "description": "Collaborative workspace for the marketing team to manage campaigns and content", "external_workspace_id": "fygr_123", "created_at": "2024-01-05T08:00:00Z", "updated_at": "2024-01-18T12:15:00Z" } } ] } ] } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/v1/medias/{id}": { "patch": { "summary": "Partially update media", "description": "Partially update an existing media record with optional file upload and metadata changes. All fields are optional.", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the media to update" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MediaPatchRequestMultipart" }, "example": { "data": "{\"type\":\"media\",\"attributes\":{\"media_type\":\"logo\"}}" } } } }, "responses": { "200": { "description": "Media updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaCreateResponse" }, "example": { "data": [ { "type": "media", "id": "media1", "attributes": { "media_type": "avatar", "url": "https://cdn.example.com/avatar.jpg", "is_primary": true, "uploaded_at": "2025-06-01T10:00:00Z", "processed_at": "2025-06-01T10:00:00Z" }, "relationships": { "people": { "data": [ { "type": "people", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77c" } ] }, "companies": { "data": [ { "type": "company", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77a" } ] }, "workspaces": { "data": [ { "type": "workspace", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77b" } ] } }, "included": [ { "type": "people", "id": "people1", "attributes": { "first_name": "John", "last_name": "Doe", "job_title": "Software Engineer", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-06-01T10:00:00Z" } }, { "type": "company", "id": "b6c22e98-c8d0-485e-9d3d-caa2bbaff77a", "attributes": { "name": "Tech Startup Inc", "description": "An innovative technology company focused on AI and ML solutions", "registration_tax_id": "12345678901", "registration_registered_value": "123456789", "created_at": "2025-08-03T10:38:40.967Z", "updated_at": "2025-08-04T07:51:01.785Z" } }, { "type": "workspace", "id": "workspace_tenant", "attributes": { "name": "Marketing Team Workspace", "description": "Collaborative workspace for the marketing team to manage campaigns and content", "external_workspace_id": "fygr_123", "created_at": "2024-01-05T08:00:00Z", "updated_at": "2024-01-18T12:15:00Z" } } ] } ] } } } }, "400": { "description": "Bad request - validation error or invalid file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/MediaNotFound" } } }, "delete": { "summary": "Delete media", "description": "Delete an existing media record and its associated file", "parameters": [ { "$ref": "#/components/parameters/AuthorizationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the media to delete" } ], "responses": { "204": { "description": "Media deleted successfully (no content)" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "$ref": "#/components/responses/MediaNotFound" } } } }, "/v1/records/{root}/filter-fields": { "get": { "operationId": "getRecordsFilterFields", "summary": "Filterable field graph for a root", "description": "Returns the filterable field graph for a record root — its scalar fields plus its one-hop relation fields — so a client can build relationship filters that aren't present in a row query's visible columns. Each entry's `path` is the dotted, GraphQL-prefixed field path; a relation field nests (`[\"invoices\",\"issuer\",\"name\"]`), which the query layer reads as a join filter for a to-one relation and an existential \"has any\" for a to-many relation (a leaf with `arrayDepth > 0`). The graph is static schema (no workspace data) and is capped at one relation hop. Feed a chosen entry's joined path into `POST /v1/records/query` as a `whereClause`.", "tags": [ "Records" ], "parameters": [ { "name": "root", "in": "path", "required": true, "description": "The record root (e.g. `companies`, `invoices`, `transactions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The root's filterable field graph.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "example": "records-filter-fields" }, "attributes": { "type": "object", "properties": { "root": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "required": [ "path", "type", "arrayDepth" ], "properties": { "path": { "type": "array", "items": { "type": "string" }, "description": "Dotted, GraphQL-prefixed field path. Length 2 = root scalar; length 3 = one-hop relation field.", "example": [ "invoices", "issuer", "name" ] }, "type": { "type": "string", "description": "Underlying column type (e.g. `string`, `numeric`, `date`, `*_enum`)." }, "arrayDepth": { "type": "integer", "description": "0 for a direct/to-one field; > 0 when reached through a to-many relation (an existential \"has any\" filter)." }, "displayType": { "type": "string" }, "enumValues": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "example": { "data": { "type": "records-filter-fields", "attributes": { "root": "invoices", "fields": [ { "path": ["invoices", "status"], "type": "invoice_status_enum", "arrayDepth": 0, "enumValues": ["draft", "issued", "paid"] }, { "path": ["invoices", "issuer", "name"], "type": "string", "arrayDepth": 0 } ] } } } } } } } } }, "/v1/records/query": { "post": { "operationId": "queryRecords", "summary": "Query records (universal read)", "description": "The universal, workspace-scoped read endpoint. Reads any of the 32 record roots through the data-views pipeline (Hasura, row-level security by workspace). Use this to read roots that do not expose a dedicated `GET /v1/` endpoint. Supports field selection, filtering, ordering, and cursor pagination.", "tags": [ "Records" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "root", "fields" ], "properties": { "root": { "type": "string", "enum": [ "companies", "people", "connectors", "workspaces", "workspace_connectors", "invoices", "documents", "transactions", "accounts", "memberships", "payment_means", "invoice_payment_means", "cards", "checks", "chat_conversations", "blueprint_runs", "ledger_accounts", "journals", "journal_entries", "tax_rates", "exchange_rates", "invoice_transactions", "media", "emails", "phones", "web_links", "locations", "categories", "invoice_items", "account_balances", "tasks", "workspace_connector_sync_logs" ], "description": "The record root to read (one of the 32 data-model roots)." }, "fields": { "type": "array", "description": "Field paths to select; each is a path array of length >= 2.", "items": { "type": "array", "items": { "type": "string" }, "minItems": 2 } }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "description": "Page size (default server-side)." }, "cursor": { "type": "string", "nullable": true, "maxLength": 4096, "description": "Opaque keyset cursor for pagination; null/absent for the first page." }, "whereClause": { "type": "object", "additionalProperties": true, "description": "Hasura-style filter object." }, "orderBy": { "type": "object", "properties": { "field": { "type": "string" }, "direction": { "type": "string", "enum": [ "asc", "desc" ] } } }, "autoZip": { "type": "boolean" }, "workspaceId": { "type": "string", "format": "uuid", "description": "Optional explicit workspace scope; the caller must have an active membership." } } }, "example": { "root": "transactions", "fields": [ [ "transactions", "id" ], [ "transactions", "instructed_amount" ] ], "limit": 50 } } } }, "responses": { "200": { "description": "Rows for the requested root with column metadata and a next cursor.", "content": { "application/json": { "example": { "data": { "rows": [], "columns": [], "cursor": null } } } } }, "400": { "description": "Validation error (unknown root, malformed fields/cursor)." }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/account-balances": { "get": { "operationId": "listAccountBalances", "summary": "List Account Balances", "description": "Workspace-scoped, cursor-paginated list of `account_balance` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of account_balance records.", "content": { "application/json": { "example": { "data": [ { "type": "account_balance", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/account-balances/{id}": { "get": { "operationId": "getAccountBalances", "summary": "Get account balance", "description": "Fetch one `account_balance` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The account_balance record.", "content": { "application/json": { "example": { "data": { "type": "account_balance", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "account_balance not found / not in workspace scope." } } } }, "/v1/accounts": { "get": { "operationId": "listAccounts", "summary": "List Accounts", "description": "Workspace-scoped, cursor-paginated list of `account` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of account records.", "content": { "application/json": { "example": { "data": [ { "type": "account", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/accounts/{id}": { "get": { "operationId": "getAccounts", "summary": "Get account", "description": "Fetch one `account` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The account record.", "content": { "application/json": { "example": { "data": { "type": "account", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "account not found / not in workspace scope." } } } }, "/v1/cards": { "get": { "operationId": "listCards", "summary": "List Cards", "description": "Workspace-scoped, cursor-paginated list of `card` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of card records.", "content": { "application/json": { "example": { "data": [ { "type": "card", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/cards/{id}": { "get": { "operationId": "getCards", "summary": "Get card", "description": "Fetch one `card` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The card record.", "content": { "application/json": { "example": { "data": { "type": "card", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "card not found / not in workspace scope." } } } }, "/v1/checks": { "get": { "operationId": "listChecks", "summary": "List Checks", "description": "Workspace-scoped, cursor-paginated list of `check` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of check records.", "content": { "application/json": { "example": { "data": [ { "type": "check", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/checks/{id}": { "get": { "operationId": "getChecks", "summary": "Get check", "description": "Fetch one `check` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The check record.", "content": { "application/json": { "example": { "data": { "type": "check", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "check not found / not in workspace scope." } } } }, "/v1/ledger-accounts": { "get": { "operationId": "listLedgerAccounts", "summary": "List Ledger Accounts", "description": "Workspace-scoped, cursor-paginated list of `ledger_account` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of ledger_account records.", "content": { "application/json": { "example": { "data": [ { "type": "ledger_account", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/ledger-accounts/{id}": { "get": { "operationId": "getLedgerAccounts", "summary": "Get ledger account", "description": "Fetch one `ledger_account` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The ledger_account record.", "content": { "application/json": { "example": { "data": { "type": "ledger_account", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "ledger_account not found / not in workspace scope." } } } }, "/v1/journals": { "get": { "operationId": "listJournals", "summary": "List Journals", "description": "Workspace-scoped, cursor-paginated list of `journal` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of journal records.", "content": { "application/json": { "example": { "data": [ { "type": "journal", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/journals/{id}": { "get": { "operationId": "getJournals", "summary": "Get journal", "description": "Fetch one `journal` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The journal record.", "content": { "application/json": { "example": { "data": { "type": "journal", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "journal not found / not in workspace scope." } } } }, "/v1/journal-entries": { "get": { "operationId": "listJournalEntries", "summary": "List Journal Entries", "description": "Workspace-scoped, cursor-paginated list of `journal_entry` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of journal_entry records.", "content": { "application/json": { "example": { "data": [ { "type": "journal_entry", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/journal-entries/{id}": { "get": { "operationId": "getJournalEntries", "summary": "Get journal entry", "description": "Fetch one `journal_entry` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The journal_entry record.", "content": { "application/json": { "example": { "data": { "type": "journal_entry", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "journal_entry not found / not in workspace scope." } } } }, "/v1/tax-rates": { "get": { "operationId": "listTaxRates", "summary": "List Tax Rates", "description": "Workspace-scoped, cursor-paginated list of `tax_rate` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of tax_rate records.", "content": { "application/json": { "example": { "data": [ { "type": "tax_rate", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/tax-rates/{id}": { "get": { "operationId": "getTaxRates", "summary": "Get tax rate", "description": "Fetch one `tax_rate` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The tax_rate record.", "content": { "application/json": { "example": { "data": { "type": "tax_rate", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "tax_rate not found / not in workspace scope." } } } }, "/v1/exchange-rates": { "get": { "operationId": "listExchangeRates", "summary": "List Exchange Rates", "description": "Workspace-scoped, cursor-paginated list of `exchange_rate` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of exchange_rate records.", "content": { "application/json": { "example": { "data": [ { "type": "exchange_rate", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/exchange-rates/{id}": { "get": { "operationId": "getExchangeRates", "summary": "Get exchange rate", "description": "Fetch one `exchange_rate` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The exchange_rate record.", "content": { "application/json": { "example": { "data": { "type": "exchange_rate", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "exchange_rate not found / not in workspace scope." } } } }, "/v1/categories": { "get": { "operationId": "listCategories", "summary": "List Categories", "description": "Workspace-scoped, cursor-paginated list of `category` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of category records.", "content": { "application/json": { "example": { "data": [ { "type": "category", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/categories/{id}": { "get": { "operationId": "getCategories", "summary": "Get category", "description": "Fetch one `category` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The category record.", "content": { "application/json": { "example": { "data": { "type": "category", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "category not found / not in workspace scope." } } } }, "/v1/invoice-transactions": { "get": { "operationId": "listInvoiceTransactions", "summary": "List Invoice Transactions", "description": "Workspace-scoped, cursor-paginated list of `invoice_transaction` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of invoice_transaction records.", "content": { "application/json": { "example": { "data": [ { "type": "invoice_transaction", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/invoice-transactions/{id}": { "get": { "operationId": "getInvoiceTransactions", "summary": "Get invoice transaction", "description": "Fetch one `invoice_transaction` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The invoice_transaction record.", "content": { "application/json": { "example": { "data": { "type": "invoice_transaction", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "invoice_transaction not found / not in workspace scope." } } } }, "/v1/media": { "get": { "operationId": "listMedia", "summary": "List Media", "description": "Workspace-scoped, cursor-paginated list of `media` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of media records.", "content": { "application/json": { "example": { "data": [ { "type": "media", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/media/{id}": { "get": { "operationId": "getMedia", "summary": "Get media", "description": "Fetch one `media` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The media record.", "content": { "application/json": { "example": { "data": { "type": "media", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "media not found / not in workspace scope." } } } }, "/v1/chat-conversations": { "get": { "operationId": "listChatConversations", "summary": "List Chat Conversations", "description": "Workspace-scoped, cursor-paginated list of `chat_conversation` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of chat_conversation records.", "content": { "application/json": { "example": { "data": [ { "type": "chat_conversation", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/chat-conversations/{id}": { "get": { "operationId": "getChatConversations", "summary": "Get chat conversation", "description": "Fetch one `chat_conversation` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The chat_conversation record.", "content": { "application/json": { "example": { "data": { "type": "chat_conversation", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "chat_conversation not found / not in workspace scope." } } } }, "/v1/workspace-connectors": { "get": { "operationId": "listWorkspaceConnectors", "summary": "List Workspace Connectors", "description": "Workspace-scoped, cursor-paginated list of `workspace_connector` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of workspace_connector records.", "content": { "application/json": { "example": { "data": [ { "type": "workspace_connector", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/workspace-connectors/{id}": { "get": { "operationId": "getWorkspaceConnectors", "summary": "Get workspace connector", "description": "Fetch one `workspace_connector` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The workspace_connector record.", "content": { "application/json": { "example": { "data": { "type": "workspace_connector", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "workspace_connector not found / not in workspace scope." } } } }, "/v1/workspace-connector-sync-logs": { "get": { "operationId": "listWorkspaceConnectorSyncLogs", "summary": "List Workspace Connector Sync Logs", "description": "Workspace-scoped, cursor-paginated list of `workspace_connector_sync_log` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of workspace_connector_sync_log records.", "content": { "application/json": { "example": { "data": [ { "type": "workspace_connector_sync_log", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/workspace-connector-sync-logs/{id}": { "get": { "operationId": "getWorkspaceConnectorSyncLogs", "summary": "Get workspace connector sync log", "description": "Fetch one `workspace_connector_sync_log` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The workspace_connector_sync_log record.", "content": { "application/json": { "example": { "data": { "type": "workspace_connector_sync_log", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "workspace_connector_sync_log not found / not in workspace scope." } } } }, "/v1/blueprint-runs": { "get": { "operationId": "listBlueprintRuns", "summary": "List Blueprint Runs", "description": "Workspace-scoped, cursor-paginated list of `blueprint_run` records. Served by the generic read-only resource handler over the data-views pipeline (Hasura row-level security).", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Page size (max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor; omit for the first page." }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "description": "Field to order by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional explicit workspace scope (Firebase-authenticated callers)." } ], "responses": { "200": { "description": "A page of blueprint_run records.", "content": { "application/json": { "example": { "data": [ { "type": "blueprint_run", "id": "uuid", "attributes": {} } ], "meta": { "total": 0, "count": 0 }, "links": { "next": null } } } } }, "401": { "description": "Unauthenticated." }, "403": { "description": "Workspace scope not permitted." } } } }, "/v1/blueprint-runs/{id}": { "get": { "operationId": "getBlueprintRuns", "summary": "Get blueprint run", "description": "Fetch one `blueprint_run` by id, workspace-scoped. Returns 404 when the id is outside the caller's workspace.", "tags": [ "Records read endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The blueprint_run record.", "content": { "application/json": { "example": { "data": { "type": "blueprint_run", "id": "uuid", "attributes": {} } } } } }, "404": { "description": "blueprint_run not found / not in workspace scope." } } } } }, "components": { "schemas": { "PersonReference": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the person" }, "attributes": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "type", "id" ] }, "CompanyReference": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the company" }, "attributes": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "logo_image": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "type", "id" ] }, "WorkspaceReference": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "attributes": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "avatar_color": { "type": "string" }, "trusted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "PersonsRelationshipData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonReference" } } } }, "CompaniesRelationshipData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyReference" } } } }, "WorkspacesRelationshipData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceReference" } } } }, "AccountRelationshipData": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means", "description": "Resource type identifier" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the payment means" }, "attributes": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account_details", "card_details", "wallet_details" ], "description": "Type of payment means" }, "status": { "type": "string", "enum": [ "pending", "active", "inactive", "suspended", "expired", "blocked" ], "default": "pending", "description": "Current status of payment means" }, "account_details": { "type": "object", "properties": { "iban": { "type": "string", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}$", "description": "International Bank Account Number" }, "bic": { "type": "string", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$", "description": "Bank Identifier Code" }, "account_number": { "type": "string", "maxLength": 50, "description": "Local account number" }, "sort_code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "UK bank sort code" }, "routing_number": { "type": "string", "pattern": "^[0-9]{9}$", "description": "US bank routing number" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Account base currency (ISO 4217)" } } }, "card_details": { "type": "object", "properties": { "masked_pan": { "type": "string", "pattern": "^\\*{4}-\\*{4}-\\*{4}-[0-9]{4}$", "description": "Masked card number" }, "brand": { "type": "string", "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay" ], "description": "Card brand" }, "card_type": { "type": "string", "enum": [ "credit", "debit", "prepaid", "corporate", "virtual" ], "description": "Card type" }, "expiry_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Card expiry month" }, "expiry_year": { "type": "integer", "minimum": 2025, "description": "Card expiry year" }, "cardholder_name": { "type": "string", "maxLength": 100, "description": "Name on card" } } }, "digital_wallet": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "paypal", "apple_pay", "google_pay", "samsung_pay", "alipay", "wechat_pay" ], "description": "Wallet provider" }, "wallet_id": { "type": "string", "maxLength": 255, "description": "Wallet identifier" }, "wallet_type": { "type": "string", "enum": [ "personal", "business", "merchant" ], "description": "Type of wallet account" } } }, "bank_details": { "type": "object", "properties": { "bank_name": { "type": "string", "maxLength": 255, "description": "Full bank name" }, "bank_code": { "type": "string", "maxLength": 20, "description": "Bank identifier code" }, "branch_name": { "type": "string", "maxLength": 255, "description": "Branch name" }, "branch_code": { "type": "string", "maxLength": 20, "description": "Branch identifier" } } }, "metadata": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "manual", "bank_feed", "api", "import", "sync" ], "description": "How this payment means was created" }, "external_id": { "type": "string", "maxLength": 255, "description": "External system identifier" } } }, "compliance": { "type": "object", "properties": { "kyc_status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "expired" ], "description": "KYC verification status" }, "aml_status": { "type": "string", "enum": [ "pending", "cleared", "flagged", "blocked" ], "description": "AML check status" }, "sanctions_check": { "type": "string", "enum": [ "pending", "passed", "flagged", "blocked" ], "description": "Sanctions screening result" }, "last_compliance_check": { "type": "string", "format": "date-time", "description": "Last compliance verification timestamp" } } }, "nickname": { "type": "string", "maxLength": 100, "description": "User-friendly name" }, "description": { "type": "string", "maxLength": 500, "description": "Additional description" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Custom tags for categorization" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } } } } } }, "TransactionRelationshipData": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "transaction", "description": "Resource type identifier" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the transaction" }, "attributes": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "sepa", "swift", "ach", "faster_payments", "instant_credit_transfer" ], "description": "Payment scheme used for the transaction" }, "external_ids": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "External transaction identifier from payment provider" }, "payment_request_id": { "type": "string", "description": "Payment request identifier" }, "end_to_end_id": { "type": "string", "description": "End-to-end reference for tracing the transaction" } } }, "requested_execution_date": { "type": "string", "format": "date", "description": "Date when transaction execution was requested" }, "executed_at": { "type": "string", "format": "date-time", "description": "Timestamp when transaction was executed" }, "booking_date": { "type": "string", "format": "date", "description": "Date when transaction was booked" }, "value_date": { "type": "string", "format": "date", "description": "Value date of the transaction" }, "instructed_amount": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "amount": { "type": "number", "minimum": 0, "description": "Amount instructed for the transaction" } } }, "settlement_amount": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "amount": { "type": "number", "minimum": 0, "description": "Amount settled for the transaction" } } }, "foreign_exchange": { "type": "object", "properties": { "currency_rate": { "type": "string", "description": "Exchange rate applied" }, "currency_pair": { "type": "string", "pattern": "^[A-Z]{6}$", "description": "Currency pair (e.g., EURUSD)" }, "currency_rate_source": { "type": "string", "description": "Source of the exchange rate" }, "currency_rate_at": { "type": "string", "format": "date-time", "description": "Timestamp when exchange rate was applied" } } }, "transaction_type": { "type": "string", "enum": [ "transfer", "direct_debit", "card_payment", "standing_order", "fee" ], "description": "Type of transaction" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "cancelled", "rejected" ], "description": "Current status of the transaction" }, "category_purpose": { "type": "string", "description": "ISO 20022 category purpose code" }, "purpose_code": { "type": "string", "description": "ISO 20022 purpose code" }, "remittance_information": { "type": "object", "properties": { "unstructured": { "type": "string", "description": "Unstructured remittance information" }, "structured_reference": { "type": "string", "description": "Structured creditor reference" }, "reference_type": { "type": "string", "enum": [ "SCOR", "RADM", "RPIN", "FXDR", "DISP", "PUOR", "SCNR" ], "description": "Type of structured reference" } } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer_fee", "exchange_fee", "processing_fee", "commission" ], "description": "Type of fee" }, "amount": { "type": "number", "minimum": 0, "description": "Fee amount" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when transaction was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when transaction was last updated" } } } } } } }, "SimpleRelationships": { "type": "object", "properties": { "persons": { "$ref": "#/components/schemas/PersonRelationRequest" }, "companies": { "$ref": "#/components/schemas/CompanyRelationRequest" }, "workspaces": { "$ref": "#/components/schemas/WorkspaceRelationRequest" } } }, "PersonRelationRequest": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "people" ] }, "id": { "type": "string", "description": "UUID of an existing people or temp-id that references an people defined in the included array" } }, "required": [ "type", "id" ] } } } }, "invoiceRelationshipDataSimple": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } }, "CompanyRelationRequest": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "id": { "type": "string", "description": "UUID of an existing companies or temp-id that references an companies defined in the included array" } }, "required": [ "type", "id" ] } } } }, "TransactionsRelationshipDataSimple": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } } } } } }, "AccountRelationshipDataSimple": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment_mean" ] }, "id": { "type": "string" } } } } }, "WorkspaceRelationRequest": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "workspace" ] }, "external_workspace_id": { "type": "string", "description": "External workspace identifier" } }, "required": [ "type", "external_workspace_id" ] }, { "properties": { "type": { "type": "string", "enum": [ "workspace" ] }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing workspace or temp-id that references an workspace defined in the included array" } }, "required": [ "type", "id" ] } ] } } } }, "WorkspacesRelationshipDataSimple": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "workspace" ] }, "external_workspace_id": { "type": "string", "description": "External workspace identifier" } } }, { "properties": { "type": { "type": "string", "enum": [ "workspace" ] }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace" } } } ] } } } }, "StandardRelationships": { "type": "object", "properties": { "persons": { "$ref": "#/components/schemas/PersonsRelationshipData" }, "companies": { "$ref": "#/components/schemas/CompaniesRelationshipData" }, "workspaces": { "$ref": "#/components/schemas/WorkspacesRelationshipData" } } }, "AtomicRelationshipsResponse": { "type": "object", "properties": { "persons": { "$ref": "#/components/schemas/PeopleRelationResponse" }, "companies": { "$ref": "#/components/schemas/CompanyRelationResponse" }, "workspaces": { "$ref": "#/components/schemas/WorkspaceRelationResponse" } } }, "WorkspaceRelationResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "workspace" ] }, "external_workspace_id": { "type": "string", "description": "External workspace identifier" } } }, { "properties": { "type": { "type": "string", "enum": [ "workspace" ] }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace" } } } ] } } } }, "PeopleRelationResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "people" ] }, "id": { "type": "string", "format": "uuid", "description": "UUID of the people" } } } } } }, "CompanyRelationResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "company" ] }, "id": { "type": "string", "format": "uuid", "description": "UUID of the company" } } } } } }, "BalanceCreateRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "balance" ] }, "attributes": { "type": "object", "properties": { "balance_at_from": { "type": "string", "format": "date-time", "description": "Define opening datetime (ISO 8601 UTC)" }, "balance_at_to": { "type": "string", "format": "date-time", "description": "Define closing datetime (ISO 8601 UTC)" } } }, "relationships": { "type": "object", "properties": { "transactions": { "$ref": "#/components/schemas/TransactionsRelationshipDataSimple" }, "account": { "$ref": "#/components/schemas/AccountRelationshipDataSimple" }, "workspaces": { "$ref": "#/components/schemas/WorkspacesRelationshipDataSimple" } }, "required": [ "account" ] } }, "required": [ "type", "attributes", "relationships" ] } }, "required": [ "data" ] }, "BalanceCreateResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "balance" ] }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "local_balance": { "type": "object", "properties": { "opening_booked": { "type": "string" }, "opening_value": { "type": "string" }, "closing_booked": { "type": "string" }, "closing_value": { "type": "string" }, "currency": { "type": "string" } } }, "accounting_balance": { "type": "object", "properties": { "opening_booked": { "type": "string" }, "opening_value": { "type": "string" }, "closing_booked": { "type": "string" }, "closing_value": { "type": "string" }, "currency": { "type": "string" } } }, "foreign_exchange": { "type": "array", "items": { "type": "object", "properties": { "currency_rate": { "type": "string" }, "currency_pair": { "type": "string" }, "currency_rate_source": { "type": "string" }, "currency_rate_at": { "type": "string" } } } }, "balance_at_from": { "type": "string" }, "balance_at_to": { "type": "string" } } }, "relationships": { "type": "object", "properties": { "transactions": { "$ref": "#/components/schemas/TransactionRelationshipData" }, "account": { "$ref": "#/components/schemas/AccountRelationshipData" }, "workspaces": { "$ref": "#/components/schemas/WorkspacesRelationshipData" } } } } } } }, "Document": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document" ] }, "attributes": { "$ref": "#/components/schemas/DocumentAttributes" }, "relationships": { "type": "object", "properties": { "company": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "id": { "type": "string" } } } } }, "people": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "people" ] }, "id": { "type": "string" }, "meta": { "type": "object", "properties": { "phone_number": { "type": "string" } } } } } } } } } } }, "DocumentAttributes": { "type": "object", "properties": { "file_name": { "type": "string" }, "status": { "type": "string" }, "uploaded_at": { "type": "string", "format": "date-time" }, "processed_at": { "type": "string", "format": "date-time" }, "file_type": { "type": "string" }, "size_bytes": { "type": "integer" } } }, "DocumentCreateAttributes": { "type": "object", "properties": { "file_name": { "type": "string" }, "status": { "type": "string" }, "file_type": { "type": "string" }, "size_bytes": { "type": "integer" } } }, "DocumentBatch": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ], "example": "document" }, "document_id": { "type": "string", "format": "uuid", "example": "bf5c55e3-133e-4660-bc27-01e8cd237c78" }, "attributes": { "$ref": "#/components/schemas/DocumentBatchAttributes" } } }, "DocumentBatchAttributes": { "type": "object", "properties": { "filename": { "type": "string", "example": "justificatif.pdf" }, "type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "example": 244158 }, "uploaded_at": { "type": "string", "format": "date-time", "example": "2025-08-25T07:40:56.297Z" } } }, "DocumentBatchResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentBatch" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "description": "Number of documents successfully returned", "example": 2 }, "requested": { "type": "integer", "description": "Number of document IDs requested", "example": 2 } } } }, "example": { "data": [ { "type": "document", "document_id": "bf5c55e3-133e-4660-bc27-01e8cd237c78", "attributes": { "filename": "justificatif.pdf", "type": "application/pdf", "size": 244158, "uploaded_at": "2025-08-25T07:40:56.297Z" } }, { "type": "document", "document_id": "2fcd94ba-7110-4af4-ad9c-ecb127430300", "attributes": { "filename": "justificatif.pdf", "type": "application/pdf", "size": 442132, "uploaded_at": "2025-08-25T10:09:43.129Z" } } ], "meta": { "total": 2, "requested": 2 } } }, "DocumentRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "attributes": { "type": "object", "properties": { "file_name": { "type": "string" } } }, "relationships": { "type": "object", "properties": { "company": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "id": { "type": "string" } } } } }, "people": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "people" ] }, "id": { "type": "string" }, "meta": { "type": "object", "properties": { "phone_number": { "type": "string" } } } } } } } } } } } } }, "WebhookSubscription": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "webhook" }, "attributes": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "document.processed" ], "description": "The event type to subscribe to" }, "target_url": { "type": "string", "format": "uri", "description": "The URL where webhook events will be sent" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "event", "target_url" ], "additionalProperties": false } }, "required": [ "type", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "WebhookResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "webhook" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the webhook subscription" }, "attributes": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "document.processed" ], "description": "The event type subscribed to" }, "target_url": { "type": "string", "format": "uri", "description": "The URL where webhook events will be sent" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Headers that will be included with webhook requests" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the webhook was created" }, "active": { "type": "boolean", "description": "Whether the webhook subscription is active" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "api-key" }, "attributes": { "type": "object", "properties": { "name": { "type": "string" }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "name", "workspace", "created_at" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false }, "CompanyRelationshipsPeopleMeta": { "type": "object", "properties": { "relationship_type": { "type": "string", "enum": [ "contact", "employee", "owner", "..." ], "description": "Type of relationship in the company. See [all company roles](/enums/company-roles) for complete list." } } }, "CompanyRelationshipsPeopleAttributesResponse": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string" }, "relationship_type": { "type": "string", "enum": [ "contact", "employee", "owner", "other" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CompanyAttributes": { "type": "object", "properties": { "description": { "type": "string" }, "domain_name_primary_link_url": { "type": "string", "format": "url", "maxLength": 500, "description": "The domain url from the website or email address of the company. Used as unique identifier in some cases.", "examples": [ "acme.com" ] }, "tax_id": { "type": "object", "properties": { "value": { "description": "Tax ID issued by local or national tax authority.", "type": "string", "examples": [ "DE123456789" ] }, "type": { "description": "Type of tax ID, useful for applying formatting and validation rules.", "type": "string", "examples": [ "VAT" ] } } }, "registration": { "type": "object", "properties": { "trade_name": { "description": "Commercial or branding name (if different from registered name).", "type": "string", "examples": [ "TechSol" ] }, "registered_name": { "description": "Legal company name.", "type": "string", "minLength": 1, "maxLength": 100, "examples": [ "Red Hat Inc." ] } } }, "registration_number": { "type": "object", "properties": { "business_type": { "description": "Legal entity structure type.", "type": "string", "examples": [ "GmbH" ] }, "value": { "description": "Official company registration number.", "type": "string", "examples": [ "HRB 123456" ] }, "registry_name": { "description": "Name of the official registration body.", "type": "string", "examples": [ "Handelsregister Berlin" ] }, "registry_country": { "description": "Country of the registry authority. (string (ISO 3166-1 alpha-2))", "type": "string", "examples": [ "DE" ] } } }, "workspace_id": { "type": "string", "format": "uuid", "description": "UUID of the workspace associated with this company" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CompanyPutAttributes": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "CompanyPostResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the created company", "example": "550e8400-e29b-41d4-a716-446655440000" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" }, "relationships": { "$ref": "#/components/schemas/CompanyRelationshipsPostResponse" }, "included": { "$ref": "#/components/schemas/CompanyIncludedResponse" } } }, "CompanyPatchRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the created company", "example": "550e8400-e29b-41d4-a716-446655440000" }, "attributes": { "$ref": "#/components/schemas/CompanyPatchAttributes" }, "relationships": { "$ref": "#/components/schemas/CompanyRelationshipsPost" }, "included": { "$ref": "#/components/schemas/CompanyIncludedPost" } } } } }, "CompanyPatchAttributes": { "type": "object", "properties": { "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "description": "Language settings.That\u2019s the locale for the business relationship. Emails or documents can be used to identify the locale. Default EN.", "example": "en-US" }, "domain_name_primary_link_url": { "type": "string", "format": "uri", "description": "The domain url from the website or email address of the company. Used as unique identifier in some cases.", "example": "https://www.techcorp.com" }, "tax_id": { "type": "object", "properties": { "value": { "type": "string", "description": "Tax ID issued by local or national tax authority.", "example": "DE123456789" }, "type": { "type": "string", "description": "Type of tax ID, useful for applying formatting and validation rules.[all tax id types](/enums/tax-id) See all available labels for complete list.", "example": [ "VAT", "TVA", "IVA", "..." ] } } }, "registration": { "oneOf": [ { "type": "object", "properties": { "trade_name": { "type": "string", "description": "Commercial or branding name (if different from registered name).", "example": "TechSol" }, "registered_name": { "type": "string", "description": "Legal company name", "example": "TechCorp AI Solutions LLC" } } }, { "type": "object", "properties": { "trade_name": { "type": "string", "description": "Commercial or branding name (if different from registered name).", "example": "TechSol" }, "registered_name": { "type": "string", "description": "Legal company name", "example": "TechCorp AI Solutions LLC" } } } ] }, "registration_number": { "type": "object", "properties": { "business_type": { "type": "string", "enum": [ "Inc", "Corp", "LLC", "GmbH", "Ltd", "SA", "SAS" ], "description": "Legal entity structure type. See [all business entity types](/enums/business-entity-by-country) for complete list.", "example": "GmbH" }, "value": { "type": "string", "description": "Official company registration number.", "example": "HRB 123456" }, "registry_name": { "type": "string", "description": "Name of the official registration body. See [all available registry name](/enums/registry-name) for complete list.", "example": "Handelsregister Berlin" }, "registry_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of the registry authority. \n Must be valid ISO country code", "example": "DE, FR, US, etc." } } }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Company description explaining business purpose in max 2 sentences.", "example": "An innovative technology company focused on AI solutions" } } }, "CompanyPost": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/CompanyRelationshipsPost" }, "included": { "$ref": "#/components/schemas/CompanyIncludedPost" } }, "required": [ "type", "attributes" ] } }, "required": [ "data", "included" ], "example": { "data": { "type": "company", "attributes": { "name": "TechCorp AI Solutions", "description": "An innovative technology company focused on AI solutions" }, "relationships": { "workspace": { "data": { "type": "workspace", "id": "temp-workspace-1" } }, "people": { "data": [ { "type": "people", "id": "temp-owner-1", "meta": { "relationship_type": "owner" } }, { "type": "people", "id": "temp-employee-1", "meta": { "relationship_type": "employee" } } ] } } }, "included": [ { "type": "workspace", "id": "temp-workspace-1", "attributes": { "workspace_id": "632860b5-48b7-49eb-9dd1-8bddc634f387" } }, { "type": "people", "id": "temp-owner-1", "attributes": { "first_name": "John", "last_name": "Doe" } }, { "type": "people", "id": "temp-employee-1", "attributes": { "first_name": "Sarah", "last_name": "Martin" } } ] } }, "CompanyRelationshipsPeopleIncludedResponse": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "people" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/CompanyRelationshipsPeopleAttributesResponse" } } } }, "CompanyCreateAttributes": { "type": "object", "properties": { "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "description": "Language settings.That\u2019s the locale for the business relationship. Emails or documents can be used to identify the locale. Default EN.", "example": "en-US" }, "domain_name_primary_link_url": { "type": "string", "format": "uri", "description": "The domain url from the website or email address of the company. Used as unique identifier in some cases.", "example": "https://www.techcorp.com" }, "tax_id": { "type": "object", "properties": { "value": { "type": "string", "description": "Tax ID issued by local or national tax authority.", "example": "DE123456789" }, "type": { "type": "string", "description": "Type of tax ID, useful for applying formatting and validation rules.[all tax id types](/enums/tax-id) See all available labels for complete list.", "example": [ "VAT", "TVA", "IVA", "..." ] } } }, "registration": { "oneOf": [ { "type": "object", "properties": { "trade_name": { "type": "string", "description": "Commercial or branding name (if different from registered name).", "example": "TechSol" }, "registered_name": { "type": "string", "description": "Legal company name", "example": "TechCorp AI Solutions LLC" } }, "required": [ "registered_name" ] }, { "type": "object", "properties": { "trade_name": { "type": "string", "description": "Commercial or branding name (if different from registered name).", "example": "TechSol" }, "registered_name": { "type": "string", "description": "Legal company name", "example": "TechCorp AI Solutions LLC" } }, "required": [ "trade_name" ] } ] }, "registration_number": { "type": "object", "properties": { "business_type": { "type": "string", "enum": [ "Inc", "Corp", "LLC", "GmbH", "Ltd", "SA", "SAS" ], "description": "Legal entity structure type. See [all business entity types](/enums/business-entity-by-country) for complete list.", "example": "GmbH" }, "value": { "type": "string", "description": "Official company registration number.", "example": "HRB 123456" }, "registry_name": { "type": "string", "description": "Name of the official registration body. See [all available registry name](/enums/registry-name) for complete list.", "example": "Handelsregister Berlin" }, "registry_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of the registry authority. \n Must be valid ISO country code", "example": "DE, FR, US, etc." } } }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Company description explaining business purpose in max 2 sentences.", "example": "An innovative technology company focused on AI solutions" } }, "required": [ "registration" ] }, "CompanyRelationshipsPost": { "type": "object", "description": "Relationships define how the company connects to other resources. To link an existing object, just put its ID. To create a new object, add it to the 'included' section with a temporary ID that matches the relationship reference.", "properties": { "media": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "description": "UUID of an existing medias or temp-id that references a medias defined in the included array", "example": "media1" } }, "required": [ "type", "id" ] } } }, "description": "Media files associated with this company. Reference by type and id. Use the 'include' query parameter to get full attributes in the included array." }, "web_links": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "web_link" }, "id": { "type": "string", "description": "UUID of an existing web-links or temp-id that references a web-links defined in the included array", "example": "sl1" } }, "required": [ "type", "id" ] } } }, "description": "Web links associated with this company. Reference by type and id. Use the 'include' query parameter to get full attributes in the included array." }, "emails": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string", "description": "UUID of an existing emails or temp-id that references a emails defined in the included array", "example": "email1" } }, "required": [ "type", "id" ] } } }, "description": "Email addresses associated with this company. Reference by type and id. Use the 'include' query parameter to get full attributes in the included array." }, "phones": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "description": "UUID of an existing phones or temp-id that references a phones defined in the included array", "example": "phone1" } }, "required": [ "type", "id" ] } } }, "description": "Phone numbers associated with this company. Reference by type and id. Use the 'include' query parameter to get full attributes in the included array." }, "locations": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "description": "UUID of an existing locations or temp-id that references a locations defined in the included array", "example": "loc1" } }, "required": [ "type", "id" ] } } }, "description": "Locations/addresses associated with this company. Reference by type and id. Use the 'include' query parameter to get full attributes in the included array." }, "people": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "description": "UUID of an existing people or temp-id that references a people defined in the included array", "example": "people1" }, "meta": { "type": "object", "properties": { "relationship_type": { "type": "string", "enum": [ "contact", "employee", "owner", "..." ], "description": "Relationship type of the person in the company. See [all company roles](/enums/company-roles) for complete list.", "example": "owner" } } } }, "required": [ "type", "id" ] } } }, "description": "People associated with this company. Reference by type and id. The meta.relationship_type field specifies the person's role. Use the 'include' query parameter to get full attributes in the included array." }, "parents": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "description": "UUID of an existing parents or temp-id that references a parents defined in the included array", "example": "parent_company1" } }, "required": [ "type", "id" ] } }, "description": "Parent company of this company. Reference by type and id. Use the 'include' query parameter to get full attributes in the included array." }, "subsidiaries": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "description": "UUID of an existing subsidiaries or temp-id that references a subsidiaries defined in the included array", "example": "subsidiary1" } }, "required": [ "type", "id" ] } } }, "description": "Subsidiary companies of this company. Reference by type and id. Use the 'include' query parameter to get full attributes in the included array." }, "workspaces": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "description": "UUID of an existing workapces or temp-id that references a workspaces defined in the included array", "example": "workspace_tenant" } }, "required": [ "type", "id" ] } } }, "description": "Workspaces associated with this company. Reference by type and id. Use the 'include' query parameter to get full attributes in the included array." } } }, "CompanyIncludedResponse": { "type": "object", "description": "Object containing included resources referenced in relationships, organized by resource type. These are the actual created/linked resources with real UUIDs.", "properties": { "created_by": { "type": "object", "description": "Person who created this company", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the person" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } } }, "people": { "type": "object", "description": "Person associated with the company", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the person" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } } }, "parents": { "type": "object", "description": "Parent company of this company", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } }, "subsidiaries": { "type": "object", "description": "Subsidiary companies of this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the subsidiary company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } } }, "workspaces": { "type": "object", "description": "Workspaces associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace" }, "attributes": { "$ref": "#/components/schemas/WorkspaceAttributes" } } } } } }, "emails": { "type": "object", "description": "Email addresses associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the email" }, "attributes": { "$ref": "#/components/schemas/EmailAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "phones": { "type": "object", "description": "Phone numbers associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the phone" }, "attributes": { "$ref": "#/components/schemas/PhoneAttributes" } } } } } }, "locations": { "type": "object", "description": "Locations/addresses associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the location" }, "attributes": { "$ref": "#/components/schemas/LocationAttributes" } } } } } }, "media": { "type": "object", "description": "Media files associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the media" }, "attributes": { "$ref": "#/components/schemas/MediaAttributes" } } } } } }, "web_links": { "type": "object", "description": "Web links associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "web_link" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the web link" }, "attributes": { "$ref": "#/components/schemas/WebLinkAttributes" } } } } } }, "documents": { "type": "object", "description": "Documents associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document" }, "attributes": { "$ref": "#/components/schemas/DocumentAttributes" } } } } } } } }, "CompanyRelationshipsPostResponse": { "type": "object", "properties": { "created_by": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the person who created this company", "example": "550e8400-e29b-41d4-a716-446655440001" } } } } }, "medias": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the media file", "example": "550e8400-e29b-41d4-a716-446655440002" } } } } } }, "web_links": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "web_link" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the web link", "example": "550e8400-e29b-41d4-a716-446655440003" } } } } } }, "emails": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the email", "example": "550e8400-e29b-41d4-a716-446655440004" } } } } } }, "phones": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the phone", "example": "550e8400-e29b-41d4-a716-446655440005" } } } } } }, "locations": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the location", "example": "550e8400-e29b-41d4-a716-446655440007" } } } } } }, "people": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the person", "example": "550e8400-e29b-41d4-a716-446655440008" }, "meta": { "type": "object", "properties": { "relationship_type": { "type": "string", "enum": [ "contact", "employee", "owner", "other" ], "description": "Relationship type of the person in the company", "example": "employee" } } } } } } } }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document", "example": "550e8400-e29b-41d4-a716-446655440009" } } } } } }, "parents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company", "example": "550e8400-e29b-41d4-a716-446655440012" } } } } } }, "subsidiaries": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the subsidiary company", "example": "550e8400-e29b-41d4-a716-446655440013" } } } } } }, "workspaces": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace", "example": "632860b5-48b7-49eb-9dd1-8bddc634f387" } } } } } } } }, "CompanyIncludedPost": { "type": "object", "description": "Object containing included resources referenced in relationships, organized by resource type.", "properties": { "people": { "type": "object", "description": "People associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "temp-id that references a person defined in the relationship array" }, "attributes": { "$ref": "#/components/schemas/PeopleCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "parents": { "type": "object", "description": "Parent company of this company", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "temp-id that references a parents defined in the relationship array" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } }, "subsidiaries": { "type": "object", "description": "Subsidiary companies of this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "temp-id that references a subsdiaries defined in the relationship array" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "workspaces": { "type": "object", "description": "Workspaces associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "temp-id that references a workspace defined in the relationship array" }, "attributes": { "$ref": "#/components/schemas/WorkspaceCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "emails": { "type": "object", "description": "Email addresses associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string", "format": "uuid", "description": "temp-id that references a emails defined in the relationship array" }, "attributes": { "$ref": "#/components/schemas/EmailCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "phones": { "type": "object", "description": "Phone numbers associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "format": "uuid", "description": "temp-id that references a phones defined in the relationship array" }, "attributes": { "$ref": "#/components/schemas/PhoneCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "locations": { "type": "object", "description": "Locations/addresses associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "temp-id that references a location defined in the relationship array" }, "attributes": { "$ref": "#/components/schemas/LocationCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "media": { "type": "object", "description": "Media files associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "temp-id that references a media defined in the relationship array" }, "attributes": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Image in png, jpg or svg format" }, "type": { "type": "string", "const": "media", "description": "Resource type identifier" }, "media_type": { "type": "string", "enum": [ "avatar", "logo", "banner" ], "description": "Type of media (avatar, logo, banner)" }, "is_primary": { "type": "boolean", "default": true, "description": "Marks preferred media. Default: true" } }, "required": [ "file", "type" ] } }, "required": [ "type", "id", "attributes" ] } } } }, "web_links": { "type": "object", "description": "Web links associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "web_link" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing web-links or temp-id that references a web-links defined in the included array" }, "attributes": { "$ref": "#/components/schemas/WebLinkCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "documents": { "type": "object", "description": "Documents associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing documents or temp-id that references a documents defined in the included array" }, "attributes": { "$ref": "#/components/schemas/DocumentCreateAttributes" }, "required": [ "type", "id", "attributes" ] } } } } } } }, "PeopleResponseRelationships": { "type": "object", "properties": { "emails": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string", "format": "uuid" } } } } } }, "phones": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "format": "uuid" } } } } } }, "web_links": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "web_link" }, "id": { "type": "string", "format": "uuid" } } } } } }, "companies": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid" }, "meta": { "type": "object", "properties": { "relationship_type": { "type": "string", "enum": [ "contact", "employee", "owner", "other" ], "description": "Relationship type of the person in the company", "example": "employee" } }, "required": [ "relationship_type" ] } }, "required": [ "type", "id", "meta" ] } } } }, "medias": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the media file", "example": "550e8400-e29b-41d4-a716-446655440002" } } } } }, "required": [ "type", "id", "meta" ] }, "workspaces": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace", "example": "632860b5-48b7-49eb-9dd1-8bddc634f387" } } } } } }, "memberships": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "memberships" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the memberships", "example": "632860b5-48b7-49eb-9dd1-8bddc634f387" } } } } } }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document", "example": "550e8400-e29b-41d4-a716-446655440009" } } } } } } } }, "PeopleResponseIncluded": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email", "description": "Type of the included email resource" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the email" }, "attributes": { "$ref": "#/components/schemas/EmailAttributes" } }, "additionalProperties": false } }, "phones": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone", "description": "Type of the included phone resource" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the phone" }, "attributes": { "$ref": "#/components/schemas/PhoneAttributes" } }, "additionalProperties": false } }, "web_links": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "social_links", "description": "Type of the included social link resource" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the social link" }, "attributes": { "$ref": "#/components/schemas/WebLinkAttributes" } }, "additionalProperties": false } }, "companies": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company", "description": "Type of the included company resource" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } }, "additionalProperties": false } }, "workspaces": { "type": "object", "description": "Workspaces associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace" }, "attributes": { "$ref": "#/components/schemas/WorkspaceCreateAttributes" } } } } } }, "medias": { "type": "object", "description": "Media files associated with this person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the media" }, "attributes": { "$ref": "#/components/schemas/MediaAttributes" } } } } } }, "memberships": { "type": "object", "description": "membership to a workspace", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the media" }, "attributes": { "$ref": "#/components/schemas/MembershipAttributes" } } } } } }, "documents": { "type": "object", "description": "Documents associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document" }, "attributes": { "$ref": "#/components/schemas/DocumentAttributes" } } } } } } }, "description": "Included resources grouped by type" }, "Invoice": { "type": "object", "properties": { "type": { "type": "string", "example": "invoice" }, "id": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/InvoiceAttributes" }, "relationships": { "$ref": "#/components/schemas/InvoiceRelationships" }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri", "description": "API link to this invoice resource" } } } }, "required": [ "type", "id", "attributes" ] }, "InvoiceAttributes": { "type": "object", "properties": { "reference_number": { "type": "string" }, "document_type": { "type": "string", "description": "Type of invoice document", "enum": [ "commercial_invoice", "credit_note", "proforma_invoice" ] }, "document_type_code": { "type": "string", "description": "UN/CEFACT code for the document type", "enum": [ "380", "381", "326" ] }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "totals": { "type": "object", "properties": { "items_total": { "type": "number" }, "tax_total": { "type": "number" }, "grand_total": { "type": "number" } } }, "terms": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "cancelled" ] }, "payment_status": { "type": "object", "properties": { "paid": { "type": "boolean" }, "amount_paid": { "type": "number" }, "amount_remaining": { "type": "number" } } }, "billing_context": { "type": "string" }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "reference_number", "issue_date", "currency", "totals", "status" ] }, "InvoiceRelationships": { "type": "object", "properties": { "issuer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "receiver": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "related_documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } }, "InvoiceItemsCreateAttributes": { "type": "object", "properties": { "line_id": { "type": "string", "description": "Line identifier within the invoice", "example": "1" }, "sku": { "type": "string", "description": "Stock Keeping Unit identifier", "example": "WM-1001" }, "name": { "type": "string", "description": "Product or service name", "example": "Wireless Mouse" }, "description": { "type": "string", "description": "Detailed description of the item", "example": "Ergonomic wireless mouse with USB receiver" }, "unit_price": { "type": "number", "format": "decimal", "minimum": 0, "description": "Unit price in local currency", "example": 25 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "EUR" }, "unit": { "type": "string", "enum": [ "EA", "HUR", "KGM", "..." ], "description": "Unit of measurement. See [all available units](/enums/invoice-line-unit) for complete list.", "example": "EA" }, "min_quantity": { "type": "integer", "minimum": 0, "description": "Minimum quantity allowed", "example": 1 }, "max_quantity": { "type": "integer", "minimum": 1, "description": "Maximum quantity allowed", "example": 500 }, "tax": { "type": "object", "properties": { "rate": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 100, "description": "Tax rate as percentage", "example": 20 }, "category": { "type": "string", "enum": [ "standard", "reduced", "exempt", "..." ], "description": "Tax category classification. See [all tax categories](/enums/tax-cat) for complete list.", "example": "standard" }, "scheme": { "type": "string", "enum": [ "VAT", "EU_VAT", "UK_VAT", "..." ], "description": "Tax scheme classification. See [all tax schemes](/enums/tax-scheme) for complete list.", "example": "VAT" } } }, "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "description": "Service period start date", "example": "2025-06-26" }, "end": { "type": "string", "format": "date", "description": "Service period end date", "example": "2025-06-27" } } } }, "required": [ "line_id", "name", "unit_price", "currency" ] }, "InvoiceItemsCreateRelationsShip": { "type": "object", "properties": { "invoices": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ] } } } }, "medias": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ] } } } } } }, "InvoiceItemPost": { "type": "object", "description": "Request schema for creating invoice items", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice_item", "description": "Resource type identifier" }, "attributes": { "$ref": "#/components/schemas/InvoiceItemsCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/InvoiceItemsCreateRelationsShip" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] }, "InvoiceItemPatch": { "type": "object", "description": "Request schema for creating invoice items", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice_item", "description": "Resource type identifier" }, "attributes": { "type": "object", "properties": { "line_id": { "type": "string", "description": "Line identifier within the invoice", "example": "1" }, "sku": { "type": "string", "description": "Stock Keeping Unit identifier", "example": "WM-1001" }, "name": { "type": "string", "description": "Product or service name", "example": "Wireless Mouse" }, "description": { "type": "string", "description": "Detailed description of the item", "example": "Ergonomic wireless mouse with USB receiver" }, "unit_price": { "type": "number", "format": "decimal", "minimum": 0, "description": "Unit price in local currency", "example": 25 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "EUR" }, "unit": { "type": "string", "enum": [ "EA", "HUR", "KGM", "..." ], "description": "Unit of measurement. See [all available units](/enums/invoice-line-unit) for complete list.", "example": "EA" }, "min_quantity": { "type": "integer", "minimum": 0, "description": "Minimum quantity allowed", "example": 1 }, "max_quantity": { "type": "integer", "minimum": 1, "description": "Maximum quantity allowed", "example": 500 }, "tax": { "type": "object", "properties": { "rate": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 100, "description": "Tax rate as percentage", "example": 20 }, "category": { "type": "string", "enum": [ "standard", "reduced", "exempt", "..." ], "description": "Tax category classification. See [all tax categories](/enums/tax-cat) for complete list.", "example": "standard" }, "scheme": { "type": "string", "enum": [ "VAT", "EU_VAT", "UK_VAT", "..." ], "description": "Tax scheme classification. See [all tax schemes](/enums/tax-scheme) for complete list.", "example": "VAT" } } }, "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "description": "Service period start date", "example": "2025-06-26" }, "end": { "type": "string", "format": "date", "description": "Service period end date", "example": "2025-06-27" } } } } }, "relationships": { "type": "object", "properties": { "invoices": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice" }, "id": { "type": "string", "format": "uuid" } } } } } }, "medias": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid" } } } } } } } } } } } }, "InvoiceItemsAttributes": { "type": "object", "properties": { "line_id": { "type": "string", "description": "Line identifier within the invoice", "example": "1" }, "sku": { "type": "string", "description": "Stock Keeping Unit identifier", "example": "WM-1001" }, "name": { "type": "string", "description": "Product or service name", "example": "Wireless Mouse" }, "description": { "type": "string", "description": "Detailed description of the item", "example": "Ergonomic wireless mouse with USB receiver" }, "unit_price": { "type": "number", "format": "decimal", "minimum": 0, "description": "Unit price in local currency", "example": 25 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "EUR" }, "unit": { "type": "string", "description": "Unit of measurement", "example": "EA" }, "min_quantity": { "type": "integer", "minimum": 0, "description": "Minimum quantity allowed", "example": 1 }, "max_quantity": { "type": "integer", "minimum": 1, "description": "Maximum quantity allowed", "example": 500 }, "tax": { "type": "object", "properties": { "rate": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 100, "description": "Tax rate as percentage", "example": 20 }, "category": { "type": "string", "description": "Tax category", "example": "standard" }, "scheme": { "type": "string", "description": "Tax scheme identifier", "example": "VAT" } } }, "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "description": "Service period start date", "example": "2025-06-26" }, "end": { "type": "string", "format": "date", "description": "Service period end date", "example": "2025-06-27" } } }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp", "example": "2025-05-11T13:42:12Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2025-05-11T13:45:20Z" } } }, "InvoiceItem": { "type": "object", "description": "Response schema for invoice items", "properties": { "type": { "type": "string", "const": "invoice_item", "description": "Resource type identifier" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the invoice item" }, "attributes": { "$ref": "#/components/schemas/InvoiceItemsAttributes" }, "relationships": { "type": "object", "properties": { "invoices": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice" }, "id": { "type": "string", "format": "uuid" } } } } }, "description": "Related invoices" }, "medias": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid" } } } } }, "description": "Related media files" } } } } }, "InvoiceItemsListResponse": { "type": "object", "description": "Response schema for listing invoice items", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" }, "description": "Array of invoice items" }, "included": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" }, "description": "Related invoice resources when included" }, "medias": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media", "description": "Resource type identifier" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the media" }, "attributes": { "type": "object", "properties": { "filename": { "type": "string", "description": "Media filename" }, "content_type": { "type": "string", "description": "MIME type of the media file" }, "size": { "type": "integer", "description": "File size in bytes" }, "url": { "type": "string", "format": "uri", "description": "Media file URL" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } } } } } }, "description": "Related resources when included via the include parameter" }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of invoice items" }, "per_page": { "type": "integer", "description": "Number of items per page" }, "current_page": { "type": "integer", "description": "Current page number" }, "total_pages": { "type": "integer", "description": "Total number of pages" } } } }, "description": "Metadata about the response" } } }, "PeoplePutAttributes": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name of the person" }, "last_name": { "type": "string", "description": "Last name of the person" } }, "additionalProperties": false }, "PeopleCreateAttributes": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "First name of the person", "example": "John" }, "last_name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Last name of the person (required)", "example": "Doe" } }, "required": [ "first_name", "last_name" ], "additionalProperties": false }, "PeopleAttributes": { "type": "object", "properties": { "first_name": { "type": "string", "description": "The person's first name" }, "last_name": { "type": "string", "description": "The person's last name" }, "full_name": { "type": "string", "description": "The person's full name (typically first_name + last_name)" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the person was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the person was last updated" } }, "additionalProperties": false }, "PeopleRelationships": { "type": "object", "properties": { "emails": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string", "description": "Temporary identifier that must match an ID in the included array" } }, "required": [ "type", "id" ] } } } }, "phones": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "description": "Temporary identifier that must match an ID in the included array" } }, "required": [ "type", "id" ] } } } }, "social_links": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "social_link" }, "id": { "type": "string", "description": "Temporary identifier that must match an ID in the included array" } }, "required": [ "type", "id" ] } } } }, "companies": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "description": "Temporary ID that matches an entry in the included array", "example": "company-2" }, "meta": { "type": "object", "properties": { "relationship_type": { "type": "string", "enum": [ "contact", "employee", "owner", "other" ], "description": "Relationship type of the person in the company", "example": "employee" } } } }, "required": [ "type", "id" ] } } } } } }, "PeopleIncluded": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object" } } } }, "PeopleIncludedPost": { "type": "object", "properties": { "emails": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/EmailAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "phones": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "description": "temp-id that references a phones defined in the included array" }, "attributes": { "$ref": "#/components/schemas/PhoneCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "web_links": { "type": "object", "description": "Web links associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "web_link" }, "id": { "type": "string", "description": "temp-id that references a web links defined in the included array" }, "attributes": { "$ref": "#/components/schemas/WebLinkCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "companies": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "description": "temp-id that references a companies defined in the included array" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "workspaces": { "type": "object", "description": "Workspaces associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "description": "temp-id that references a workspaces defined in the included array" }, "attributes": { "$ref": "#/components/schemas/WorkspaceCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "documents": { "type": "object", "description": "Documents associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "description": "temp-id that references a documents defined in the included array" }, "attributes": { "$ref": "#/components/schemas/DocumentCreateAttributes" } } } } } }, "memberships": { "type": "object", "description": "membership associated with this person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "membership" }, "id": { "type": "string", "description": "temp-id that references a memberships defined in the included array" }, "attributes": { "$ref": "#/components/schemas/MembershipCreateAttributes" } } } } } }, "medias": { "type": "object", "description": "Media associated with this person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "membership" }, "id": { "type": "string", "description": "temp-id that references a medias defined in the included array" }, "attributes": { "$ref": "#/components/schemas/MediaCreateAttributes" } } } } } } } }, "PeopleResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "example": "people" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Person's first name", "example": "John" }, "last_name": { "type": "string", "description": "Person's last name", "example": "Doe" }, "full_name": { "type": "string", "description": "Person's full name (first + last)", "example": "John Doe" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the person was created", "example": "2024-01-15T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the person was last updated", "example": "2024-01-20T14:45:00Z" } } }, "relationships": { "$ref": "#/components/schemas/PeopleResponseRelationships" }, "included": { "$ref": "#/components/schemas/PeopleResponseIncluded" } } } } }, "PeopleRelationshipsCompaniesRequest": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the existing company to link" }, "meta": { "type": "object", "properties": { "relationship_type": { "type": "string", "enum": [ "contact", "employee", "owner", "other" ], "description": "Type of relationship with the company" } } } }, "required": [ "type", "id" ] } } }, "required": [ "data" ] }, "PeopleRelationshipsCompaniesIncluded": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "company" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "PeopleRelationshipsCompaniesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "company" }, "id": { "type": "string", "format": "uuid" } } } }, "included": { "$ref": "#/components/schemas/PeopleRelationshipsCompaniesIncluded" } } }, "PhoneCreateRequest": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/PhoneCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/PhoneRelationships" } }, "required": [ "attributes", "relationships" ] }, "PhoneCreateAttributes": { "type": "object", "properties": { "number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "Phone number in E164 format", "example": "+14155552671" }, "is_primary": { "type": "boolean", "description": "Whether this is the primary phone number", "default": true }, "label": { "type": "string", "enum": [ "work", "personal", "other", "..." ], "description": "Phone label type. See [all available labels](/enums/label) for complete list.", "default": "work" } }, "required": [ "number" ] }, "PhoneRelationships": { "$ref": "#/components/schemas/AtomicRelationshipsResponse" }, "Phone": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the phone" }, "attributes": { "$ref": "#/components/schemas/PhoneAttributes" }, "relationships": { "$ref": "#/components/schemas/AtomicRelationshipsResponse" }, "included": { "$ref": "#/components/schemas/SimpleIncludedResponse" } } }, "PhoneAttributes": { "type": "object", "properties": { "number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "Full international phone number in E164 format", "example": "+14155552671" }, "label": { "type": "string", "enum": [ "work", "personal", "other", "..." ], "description": "Phone label type. See [all available labels](/enums/label) for complete list." }, "is_primary": { "type": "boolean", "description": "Whether this is the primary phone number" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the phone was created" } } }, "PhoneGetResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Phone" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of phones" }, "count": { "type": "integer", "description": "Number of phones in current response" }, "has_more": { "type": "boolean", "description": "Whether there are more phones available" }, "next_cursor": { "type": "string", "description": "Cursor for the next page of results" } } } } } } }, "PhoneCreateResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Phone" } } } }, "EmailCreateRequest": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/EmailAttributes" }, "relationships": { "$ref": "#/components/schemas/SimpleRelationships" } }, "required": [ "attributes", "relationships" ] }, "EmailAttributes": { "type": "object", "properties": { "value": { "type": "string", "format": "email", "description": "Email address value", "example": "sarah.wilson@techcorp.com" }, "is_primary": { "type": "boolean", "default": true, "description": "Whether this is the primary email address. Defaults to 'false', unless no other email is marked as primary (in which case it becomes 'true'). Only one email can be marked as primary per person/company.", "example": true }, "label": { "type": "string", "enum": [ "work", "personal", "other", "..." ], "description": "Email label type. See [all available labels](/enums/label) for complete list.", "default": "work", "example": "work" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the email was created", "example": "2023-06-15T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the email was last updated", "example": "2023-06-15T10:30:00Z" } } }, "EmailCreateAttributes": { "type": "object", "properties": { "value": { "type": "string", "format": "email", "description": "Email address value", "example": "sarah.wilson@techcorp.com" }, "is_primary": { "type": "boolean", "default": true, "description": "Whether this is the primary email address. Defaults to 'false', unless no other email is marked as primary (in which case it becomes 'true'). Only one email can be marked as primary per person/company.", "example": true }, "label": { "type": "string", "enum": [ "work", "personal", "other", "..." ], "description": "Email label type. See [all available labels](/enums/label) for complete list.", "default": "work", "example": "work" } } }, "Email": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/EmailAttributes" }, "relationships": { "$ref": "#/components/schemas/AtomicRelationshipsResponse" }, "included": { "$ref": "#/components/schemas/SimpleIncludedResponse" } } }, "SimpleIncludedResponse": { "type": "object", "properties": { "persons": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/PersonAttributes" } } } } } }, "companies": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } } }, "workspaces": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/WorkspaceAttributes" } } } } } } } }, "EmailCreateResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } } } }, "EmailGetResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of emails" }, "count": { "type": "integer", "description": "Number of emails in current response" }, "has_more": { "type": "boolean", "description": "Whether there are more emails available" }, "next_cursor": { "type": "string", "description": "Cursor for the next page of results" } } } } } } }, "EmailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Email" } } }, "PhoneResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Phone" } } }, "MembershipAttributes": { "type": "object", "properties": { "role": { "type": "string" }, "firebase_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MembershipRelationships": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "person": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } }, "MembershipCreateAttributes": { "type": "object", "properties": { "firebase_id": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member", "owner", "..." ], "description": "User role in the workspace. See [all available roles](/enums/role) for complete list." } }, "required": [ "role" ] }, "MembershipCreateRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "membership" }, "attributes": { "$ref": "#/components/schemas/MembershipCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/MembershipRelationships" } }, "required": [ "type", "attributes", "relationships" ] } }, "required": [ "data" ] }, "MembershipResource": { "type": "object", "properties": { "type": { "type": "string", "const": "membership" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/MembershipAttributes" }, "relationships": { "$ref": "#/components/schemas/MembershipRelationships" } } }, "MembershipCreateResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MembershipResource" } } }, "MembershipListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "size": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } }, "MembershipGetResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MembershipResource" } } }, "MembershipUpdateAttributes": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member", "owner", "..." ], "description": "User role in the workspace. See [all available roles](/enums/role) for complete list." }, "firebase_id": { "type": "string", "minLength": 1 } } }, "MembershipUpdateRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "membership" }, "attributes": { "$ref": "#/components/schemas/MembershipUpdateAttributes" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] }, "MembershipUpdateResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MembershipResource" } } }, "WorkspaceRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "attributes": { "$ref": "#/components/schemas/WorkspaceCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/WorkspaceRelationshipsRequest" }, "included": { "$ref": "#/components/schemas/WorkspaceIncludedRequest" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] }, "WorkspaceRelationshipsRequest": { "type": "object", "properties": { "owner": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing people or temp-id that references a people defined in the included array" } }, "required": [ "type", "id" ] } } } } }, "WorkspaceIncludedRequest": { "type": "object", "properties": { "owner": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a people in the relationships" }, "attributes": { "$ref": "#/components/schemas/PeopleCreateAttributes" } }, "required": [ "type", "id" ] } } } } }, "WorkspaceCreateAttributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workspace name" }, "description": { "type": "string", "maxLength": 1000, "description": "Workspace description" }, "avatar_color": { "type": "string", "pattern": "^#[A-Fa-f0-9]{6}$", "description": "Avatar color in hexadecimal format (e.g., #FF5733)" }, "external_workspace_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "External workspace identifier" } }, "required": [ "name" ] }, "WorkspaceResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/WorkspaceAttributes" }, "relationships": { "$ref": "#/components/schemas/WorkspaceRelationshipsResponse" }, "included": { "$ref": "#/components/schemas/WorkspaceIncludedipsResponse" } } } } }, "WorkspaceRelationshipsResponse": { "type": "object", "properties": { "owner": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } }, "WorkspaceIncludedipsResponse": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "people", "examples": [ "peoplex" ] }, "id": { "type": "string", "example": "temp-people1" }, "attributes": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "full_name": { "type": "string", "example": "John Doe" }, "created_at": { "type": "string", "format": "timestamp" }, "updated_at": { "type": "string", "format": "timestamp" } } } } } }, "WorkspacePutAttributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workspace name" }, "description": { "type": "string", "maxLength": 1000, "description": "Workspace description" } } }, "WorkspacePutRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "attributes": { "$ref": "#/components/schemas/WorkspacePutAttributes" }, "relationship": { "$ref": "#/components/schemas/WorkspaceRelationshipsRequest" }, "included": { "$ref": "#/components/schemas/WorkspaceIncludedRequest" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] }, "Person": { "type": "object", "description": "Central entity representing individuals with comprehensive contact information", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique person identifier (UUID v4)", "example": "550e8400-e29b-41d4-a716-446655440000" }, "type": { "type": "string", "const": "people", "description": "JSON:API resource type identifier" }, "attributes": { "$ref": "#/components/schemas/PersonAttributes" }, "relationships": { "$ref": "#/components/schemas/PersonRelationships" }, "included": { "$ref": "#/components/schemas/PeopleIncludedPost" } }, "required": [ "id", "type", "attributes" ] }, "PersonAttributes": { "type": "object", "description": "Person attribute data", "properties": { "first_name": { "type": "string", "description": "Person's first name", "example": "Marie", "minLength": 1, "maxLength": 100 }, "last_name": { "type": "string", "description": "Person's last name", "example": "Dubois", "minLength": 1, "maxLength": 100 }, "full_name": { "type": "string", "description": "Auto-computed full name (first + last)", "example": "Marie Dubois", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Person creation timestamp (UTC)", "example": "2024-01-15T10:30:00Z", "readOnly": true }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last modification timestamp (UTC)", "example": "2024-01-16T14:20:00Z", "readOnly": true } }, "required": [ "first_name", "last_name", "created_at" ] }, "PersonRelationships": { "type": "object", "description": "Person relationship references", "properties": { "emails": { "type": "object", "description": "Email addresses associated with this person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "id": { "type": "string", "description": "UUID of an existing email or temp-id that references an email defined in the included array" } }, "required": [ "type", "id" ] } } } }, "phones": { "type": "object", "description": "Phone numbers associated with this person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "phone" }, "id": { "type": "string", "description": "UUID of an existing phone or temp-id that references a phone defined in the included array" } }, "required": [ "type", "id" ] } } } }, "web_links": { "type": "object", "description": "Social media profiles associated with this person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "social_link" }, "id": { "type": "string", "description": "UUID of an existing web link or temp-id that references a web link defined in the included array" } }, "required": [ "type", "id" ] } } } }, "companies": { "type": "object", "description": "Companies associated with this person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "description": "UUID of an existing company or temp-id that references a company defined in the included array" } }, "required": [ "type", "id" ] } } } }, "workspaces": { "type": "object", "description": "Workspaces this person belongs to", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "description": "UUID of an existing workspace or temp-id that references a workspace defined in the included array" } }, "required": [ "type", "id" ] } } } }, "documents": { "type": "object", "description": "Documents associated with this person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "description": "UUID of an existing document or temp-id that references a document defined in the included array" } }, "required": [ "type", "id" ] } } } }, "memberships": { "type": "object", "description": "Workspace memberships with roles and permissions", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "membership" }, "id": { "type": "string", "description": "UUID of an existing membership or temp-id that references a membership defined in the included array" } }, "required": [ "type", "id" ] } } } }, "medias": { "type": "object", "description": "medias of the person", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "description": "UUID of an existing media or temp-id that references a media defined in the included array" } }, "required": [ "type", "id" ] } } } } } }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "status", "code", "title", "detail" ] } } } }, "BadRequestError": { "type": "object", "properties": { "code": { "type": "string", "example": "SCHEMA_VALIDATION_ERROR", "description": "Error code identifier" }, "status": { "type": "integer", "example": 400, "description": "HTTP status code" }, "title": { "type": "string", "example": "Validation Error", "description": "Error title" }, "message": { "type": "string", "example": "The request is invalid", "description": "Detailed error message" }, "details": { "type": "array", "items": { "type": "object", "properties": { "instancePath": { "type": "string", "description": "Path to the invalid field in the request" }, "schemaPath": { "type": "string", "description": "Path to the validation rule in the schema" }, "keyword": { "type": "string", "description": "Validation keyword that failed" }, "params": { "type": "object", "description": "Parameters related to the validation failure" }, "message": { "type": "string", "description": "Human-readable validation error message" } } }, "description": "Array of detailed validation errors" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] }, "MediaPost": { "type": "object", "properties": { "type": { "type": "string", "const": [ "medias" ], "examples": [ "medias" ] }, "attributes": { "$ref": "#/components/schemas/MediaAttributesJson" }, "relationship": { "type": "object", "properties": { "persons": { "$ref": "#/components/schemas/PersonRelationRequest" }, "companies": { "$ref": "#/components/schemas/CompanyRelationRequest" }, "workspaces": { "$ref": "#/components/schemas/WorkspaceRelationRequest" }, "invoice_items": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice_item" }, "id": { "type": "string", "example": "pm_1", "description": "UUID of an existing invoice item or temp-id that references an invoice item defined in the included array" } } } } }, "description": "Line items included in the invoice" } } } } }, "MediaAttributesJson": { "type": "object", "properties": { "media_type": { "type": "string", "enum": [ "avatar", "logo", "banner" ], "description": "Type of media (avatar, logo, banner) See [Media type documentation](/enums/media) for complete list." }, "is_primary": { "type": "boolean", "default": true, "description": "Marks preferred media. Default: true" }, "url": { "type": "string", "format": "uri", "description": "Direct media URL", "examples": [ "https://cdn.example.com/avatar.jpg" ] } }, "required": [ "media_type", "url" ] }, "MediaCreateRequestMultipart": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Image in png, jpg or svg format" }, "data.type": { "type": "string", "const": "media", "description": "Resource type identifier" }, "data.attributes.media_type": { "type": "string", "enum": [ "avatar", "logo", "banner" ], "description": "Type of media (avatar, logo, banner)" }, "data.attributes.is_primary": { "type": "boolean", "default": true, "description": "Marks preferred media. Default: true" }, "data.relationships.people.data[].type": { "type": "string", "const": "people", "description": "Type for people relationship" }, "data.relationships.people.data[].id": { "type": "string", "format": "uuid", "description": "UUID of the person to associate with this media" }, "data.relationships.companies.data[].type": { "type": "string", "const": "company", "description": "Type for company relationship" }, "data.relationships.companies.data[].id": { "type": "string", "format": "uuid", "description": "UUID of the company to associate with this media" }, "data.relationships.workspaces.data[].type": { "type": "string", "const": "workspace", "description": "Type for workspace relationship" }, "data.relationships.workspaces.data[].id": { "type": "string", "format": "uuid", "description": "UUID of the workspace to associate with this media" }, "data.relationships.workspaces.data[].external_workspace_id": { "type": "string", "format": "uuid", "description": "UUID of the external workspace to associate with this media" } }, "required": [ "file", "data.type" ] }, "MediaPatchRequestMultipart": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Image in png, jpg or svg format (optional for PATCH)" }, "data.type": { "type": "string", "const": "media", "description": "Resource type identifier (optional for PATCH)" }, "data.attributes.media_type": { "type": "string", "enum": [ "avatar", "logo", "banner" ], "description": "Type of media (avatar, logo, banner) (optional for PATCH)" }, "data.attributes.is_primary": { "type": "boolean", "description": "Marks preferred media (optional for PATCH)" }, "data.relationships.people.data[].type": { "type": "string", "const": "people", "description": "Type for people relationship (optional for PATCH)" }, "data.relationships.people.data[].id": { "type": "string", "format": "uuid", "description": "UUID of the person to associate with this media (optional for PATCH)" }, "data.relationships.companies.data[].type": { "type": "string", "const": "company", "description": "Type for company relationship (optional for PATCH)" }, "data.relationships.companies.data[].id": { "type": "string", "format": "uuid", "description": "UUID of the company to associate with this media (optional for PATCH)" }, "data.relationships.workspaces.data[].type": { "type": "string", "const": "workspace", "description": "Type for workspace relationship (optional for PATCH)" }, "data.relationships.workspaces.data[].id": { "type": "string", "format": "uuid", "description": "UUID of the workspace to associate with this media (optional for PATCH)" } } }, "MediaCreateAttributes": { "type": "object", "properties": { "media_type": { "type": "string", "enum": [ "avatar", "logo", "banner" ], "description": "Type of media (avatar, logo, banner)" }, "is_primary": { "type": "boolean", "default": true, "description": "Marks preferred media. Default: true" } } }, "MediaCreateResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/MediaAttributes" }, "relationships": { "$ref": "#/components/schemas/MediaResponseRelationships" }, "included": { "$ref": "#/components/schemas/MediaResponseIncluded" } } } } }, "MediaResponseIncluded": { "type": "object", "properties": { "people": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } } } }, "companies": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } } }, "workspaces": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/WorkspaceAttributes" } } } } } }, "invoice_item": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice_item" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/InvoiceItemsAttributes" } } } } } } } }, "MediaAttributes": { "type": "object", "properties": { "media_type": { "type": "string", "enum": [ "avatar", "logo", "banner" ] }, "url": { "type": "string", "format": "uri", "description": "URL to the media file" }, "is_primary": { "type": "boolean", "description": "Whether this is the primary media" }, "processed_at": { "type": [ "string" ], "format": "date-time", "description": "Timestamp when media processing completed" }, "uploaded_at": { "type": "string", "format": "date-time" } } }, "MediaRequestAttributes": { "type": "object", "properties": { "media_type": { "type": "string", "enum": [ "avatar", "logo", "banner" ] }, "url": { "type": "string", "format": "uri", "description": "URL to the media file" }, "is_primary": { "type": "boolean", "description": "Whether this is the primary media" }, "processed_at": { "type": [ "string" ], "format": "date-time", "description": "Timestamp when media processing completed" }, "uploaded_at": { "type": "string", "format": "date-time" } } }, "MediaResponseRelationships": { "type": "object", "properties": { "people": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid" } } } } } }, "companies": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid" } } } } } }, "workspaces": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid" } } } } } } } }, "TransactionIncludedPost": { "type": "object", "properties": { "debtor_payment_means": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "description": "Temp-id that references a payment means in the relationships" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansCreateAttributes" } } }, "creditor_payment_means": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_mean" }, "id": { "type": "string", "description": "Temp-id that references a creditor payment means in the relationships" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansCreateAttributes" } } }, "debtor": { "type": "object", "properties": { "attributes": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": [ "company" ] }, "id": { "type": "string", "description": "Temp-id that references a debtor in the relationships" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } } }, { "type": "object", "properties": { "type": { "type": "string", "const": [ "people" ], "description": "Type of debtor entity" }, "id": { "type": "string", "description": "Temp-id that references a debtor in the relationships" }, "attributes": { "$ref": "#/components/schemas/PeopleCreateAttributes" } } } ] } } }, "creditor": { "type": "object", "properties": { "attributes": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": [ "company" ] }, "id": { "type": "string", "description": "Temp-id that references a creditor in the relationships" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } } }, { "type": "object", "properties": { "type": { "type": "string", "const": [ "people" ], "description": "Type of debtor entity" }, "id": { "type": "string", "description": "Temp-id that references a creditor in the relationships" }, "attributes": { "$ref": "#/components/schemas/PeopleCreateAttributes" } } } ] } } }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "invoice" ] }, "id": { "type": "string", "description": "Temp-id that references a documents in the relationships" }, "attributes": { "$ref": "#/components/schemas/DocumentCreateAttributes" } } } } } }, "created_by": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "description": "Temp-id that references a people who create the transaction in the relationships" }, "attributes": { "$ref": "#/components/schemas/PeopleCreateAttributes" } } } } }, "workspaces": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "description": "Temp-id that workspaces a creditor in the relationships" }, "attributes": { "$ref": "#/components/schemas/WorkspaceCreateAttributes" } } } } } } }, "TransactionPost": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "transaction", "description": "Resource type identifier" }, "attributes": { "$ref": "#/components/schemas/TransactionAttributesPost" }, "relationships": { "$ref": "#/components/schemas/TransactionRelationshipsPost" }, "included": { "$ref": "#/components/schemas/TransactionIncludedPost" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] }, "TransactionIncludedPostResponse": { "type": "object", "properties": { "debtor_payment_means": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the debtor payment means (source)" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansAttributes" } } } } }, "creditor_payment_means": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the creditor payment means (destination)" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansAttributes" } } } } }, "debtor": { "type": "object", "properties": { "attributes": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": [ "company" ] }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } }, { "type": "object", "properties": { "type": { "type": "string", "const": [ "people" ], "description": "Type of debtor entity" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } ] } } }, "creditor": { "type": "object", "properties": { "attributes": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": [ "company" ] }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } }, { "type": "object", "properties": { "type": { "type": "string", "const": [ "people" ], "description": "Type of debtor entity" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } ] } } }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "invoice" ], "description": "Type of document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document (receipts, confirmations, invoices)" }, "attributes": { "$ref": "#/components/schemas/DocumentAttributes" } } } } } }, "created_by": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the user who created the transaction record" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } } }, "workspaces": { "type": "object", "properties": { "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace associated with this transaction" }, "attributes": { "$ref": "#/components/schemas/WorkspaceAttributes" } } } } } } }, "TransactionResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "transaction" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the created transaction", "example": "550e8400-e29b-41d4-a716-446655440010" }, "attributes": { "$ref": "#/components/schemas/TransactionAttributes" }, "relationships": { "$ref": "#/components/schemas/TransactionRelationshipsPostResponse" }, "included": { "$ref": "#/components/schemas/TransactionIncludedPostResponse" } } } } }, "TransactionAttributesPost": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "sepa", "swift", "ach", "..." ], "description": "Payment scheme used. See [payment schemes documentation](/enums/scheme-type) for complete list." }, "external_ids": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "External transaction identifier from payment provider" }, "payment_request_id": { "type": "string", "description": "Payment request identifier" }, "end_to_end_id": { "type": "string", "description": "End-to-end reference for tracing the transaction" } } }, "requested_execution_date": { "type": "string", "format": "date", "description": "Date when transaction execution was requested" }, "executed_at": { "type": "string", "format": "date-time", "description": "Timestamp when transaction was executed" }, "booking_date": { "type": "string", "format": "date", "description": "Date when transaction was booked" }, "value_date": { "type": "string", "format": "date", "description": "Value date of the transaction" }, "instructed_amount": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "amount": { "type": "number", "minimum": 0, "description": "Amount instructed for the transaction" } }, "required": [ "currency", "amount" ] }, "settlement_amount": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "amount": { "type": "number", "minimum": 0, "description": "Amount settled for the transaction" } } }, "foreign_exchange": { "type": "object", "properties": { "currency_rate": { "type": "string", "description": "Exchange rate applied" }, "currency_pair": { "type": "string", "pattern": "^[A-Z]{6}$", "description": "Currency pair (e.g., EURUSD)" }, "currency_rate_source": { "type": "string", "enum": [ "provider", "market", "custom" ], "description": "Source of the exchange rate" }, "currency_rate_at": { "type": "string", "format": "date-time", "description": "Timestamp when exchange rate was applied" } } }, "transaction_type": { "type": "string", "enum": [ "payment", "transfer", "deposit", "..." ], "description": "Type of transaction. See [transaction types documentation](/enums/transaction) for complete list." }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "..." ], "description": "Current status of the transaction. See [transaction status documentation](/enums/details-banking-transaction-status) for complete list." }, "category_purpose": { "type": "string", "description": "ISO 20022 category purpose code" }, "purpose_code": { "type": "string", "description": "ISO 20022 purpose code" }, "remittance_information": { "type": "object", "properties": { "unstructured": { "type": "string", "description": "Unstructured remittance information" }, "structured_reference": { "type": "string", "description": "Structured creditor reference" }, "reference_type": { "type": "string", "enum": [ "SCOR", "RADM", "RPIN", "FXDR", "DISP", "PUOR", "SCNR" ], "description": "Type of structured reference. See [remittance reference types](/enums/remittance-info-reference) for details." } } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer_fee", "exchange_fee", "processing_fee", "..." ], "description": "Type of fee. See [banking transaction fees](/enums/banking-transaction-fee) for details." }, "amount": { "type": "number", "minimum": 0, "description": "Fee amount" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "type", "amount", "currency" ] } } }, "required": [ "instructed_amount", "scheme", "executed_at" ] }, "TransactionAttributes": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "sepa", "swift", "ach", "faster_payments", "instant_credit_transfer" ], "description": "Payment scheme used for the transaction" }, "external_ids": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "External transaction identifier from payment provider" }, "payment_request_id": { "type": "string", "description": "Payment request identifier" }, "end_to_end_id": { "type": "string", "description": "End-to-end reference for tracing the transaction" } } }, "requested_execution_date": { "type": "string", "format": "date", "description": "Date when transaction execution was requested" }, "executed_at": { "type": "string", "format": "date-time", "description": "Timestamp when transaction was executed" }, "booking_date": { "type": "string", "format": "date", "description": "Date when transaction was booked" }, "value_date": { "type": "string", "format": "date", "description": "Value date of the transaction" }, "instructed_amount": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "amount": { "type": "number", "minimum": 0, "description": "Amount instructed for the transaction" } } }, "settlement_amount": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "amount": { "type": "number", "minimum": 0, "description": "Amount settled for the transaction" } } }, "foreign_exchange": { "type": "object", "properties": { "currency_rate": { "type": "string", "description": "Exchange rate applied" }, "currency_pair": { "type": "string", "pattern": "^[A-Z]{6}$", "description": "Currency pair (e.g., EURUSD)" }, "currency_rate_source": { "type": "string", "description": "Source of the exchange rate" }, "currency_rate_at": { "type": "string", "format": "date-time", "description": "Timestamp when exchange rate was applied" } } }, "transaction_type": { "type": "string", "enum": [ "payment", "transfer", "deposit", "withdrawal", "card_payment", "direct_debit", "refund", "fee", "interest", "other" ], "description": "Type of transaction. See [transaction types documentation](/enums/transaction) for complete list." }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "cancelled", "rejected" ], "description": "Current status of the transaction" }, "category_purpose": { "type": "string", "description": "ISO 20022 category purpose code" }, "purpose_code": { "type": "string", "description": "ISO 20022 purpose code" }, "remittance_information": { "type": "object", "properties": { "unstructured": { "type": "string", "description": "Unstructured remittance information" }, "structured_reference": { "type": "string", "description": "Structured creditor reference" }, "reference_type": { "type": "string", "enum": [ "SCOR", "RADM", "RPIN", "FXDR", "DISP", "PUOR", "SCNR" ], "description": "Type of structured reference. See [remittance reference types](/enums/remittance-info-reference) for details." } } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer_fee", "exchange_fee", "processing_fee", "commission" ], "description": "Type of fee. See [banking transaction fees](/enums/banking-transaction-fee) for details." }, "amount": { "type": "number", "minimum": 0, "description": "Fee amount" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when transaction was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when transaction was last updated" } } }, "TransactionRelationshipsPost": { "type": "object", "properties": { "debtor_payment_means": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing payment means or temp-id that references a payment means defined in the included array (source account)" } }, "required": [ "type", "id" ] } }, "required": [ "data" ] }, "creditor_payment_means": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing payment means or temp-id that references a payment means defined in the included array (destination account)" } }, "required": [ "type", "id" ] } }, "required": [ "data" ] }, "debtor": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "people" ], "description": "Type of debtor entity" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing company or person, or temp-id that references an entity defined in the included array (entity that initiated the payment)" } }, "required": [ "type", "id" ] } } }, "creditor": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "people" ], "description": "Type of creditor entity" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing company or person, or temp-id that references an entity defined in the included array (entity that received the payment)" } }, "required": [ "type", "id" ] } } }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "invoice" ], "description": "Type of document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing document or invoice, or temp-id that references a document defined in the included array)" } }, "required": [ "type", "id" ] } } } }, "created_by": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing person or temp-id that references a person defined in the included array (user who created the transaction record)" } }, "required": [ "type", "id" ] } } }, "workspaces": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing workspace or temp-id that references a workspace defined in the included array" } }, "required": [ "type", "id" ] } } } } }, "required": [ "debtor_payment_means", "creditor_payment_means" ] }, "TransactionRelationshipsPostResponse": { "type": "object", "properties": { "debtor_payment_means": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the debtor payment means (source)" } } } } }, "creditor_payment_means": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the creditor payment means (destination)" } } } } }, "debtor": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "people" ], "description": "Type of debtor entity" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the debtor (entity that initiated the payment)" } } } } }, "creditor": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "people" ], "description": "Type of creditor entity" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the creditor (entity that received the payment)" } } } } }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "invoice" ], "description": "Type of document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document (receipts, confirmations, invoices)" } } } } } }, "created_by": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the user who created the transaction record" } } } } }, "workspaces": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace associated with this transaction" } } } } } } } }, "PaymentMeansIncluded": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_details", "account_details", "wallet_details", "cash_details", "check_details", "crypto_details", "other" ], "description": "Type of payment means. See [payment means types](/enums/payment-means) for details." }, "status": { "type": "string", "enum": [ "active", "inactive", "pending_verification", "suspended", "expired", "blocked" ], "description": "Current status of the payment means. See [payment means status](/enums/payment-means-status) for details." }, "nickname": { "type": "string", "description": "User-friendly name for the payment means" }, "description": { "type": "string", "description": "Additional description of the payment means" } } } } }, "PaymentMeansPatch": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "attributes": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_details", "account_details", "wallet_details", "..." ], "description": "Type of payment means. See [payment means types](/enums/payment-means) for details." }, "scheme": { "type": "string", "enum": [ "SEPA", "SWIFT", "ACH", "..." ], "description": "Payment scheme or network. See [scheme types](/enums/sheme-type) for details." }, "status": { "type": "string", "enum": [ "active", "inactive", "pending_verification", "suspended", "expired", "blocked" ], "description": "Current status of the payment means. See [payment means status](/enums/payment-means-status) for details." }, "account_details": { "type": "object", "description": "Bank account details for account_details type", "properties": { "iban": { "type": "string", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]+$", "description": "International Bank Account Number" }, "bic": { "type": "string", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$", "description": "Bank Identifier Code (SWIFT)" }, "sort_code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Bank sort code (UK)" }, "account_number": { "type": "string", "description": "Local account number (alternative to IBAN)" }, "routing_number": { "type": "string", "description": "Bank routing number (US ACH)" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency code (ISO 4217)" } } }, "bank_details": { "type": "object", "description": "Additional bank information", "properties": { "bank_name": { "type": "string", "description": "Name of the bank" }, "bank_code": { "type": "string", "description": "Bank code or identifier" }, "branch_name": { "type": "string", "description": "Bank branch name" }, "branch_code": { "type": "string", "description": "Bank branch code" } } }, "card_details": { "type": "object", "description": "Credit/debit card details for card_details type", "properties": { "masked_pan": { "type": "string", "pattern": "^\\*{4}-\\*{4}-\\*{4}-[0-9]{4}$", "description": "Masked Primary Account Number (PCI DSS compliant)" }, "brand": { "type": "string", "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "other" ], "description": "Card brand" }, "card_type": { "type": "string", "enum": [ "credit", "debit", "prepaid", "charge" ], "description": "Type of card" }, "expiry_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Card expiry month" }, "expiry_year": { "type": "integer", "minimum": 2024, "description": "Card expiry year" }, "cardholder_name": { "type": "string", "description": "Name as printed on card" } } }, "digital_wallet": { "type": "object", "description": "Digital wallet details for wallet_details type", "properties": { "provider": { "type": "string", "enum": [ "paypal", "applepay", "googlepay", "stripe", "square", "venmo", "cashapp", "other" ], "description": "Digital wallet provider" }, "wallet_id": { "type": "string", "description": "Wallet identifier (email, phone, etc.)" }, "wallet_type": { "type": "string", "enum": [ "personal", "business", "merchant" ], "description": "Type of wallet account" } } }, "compliance": { "type": "object", "description": "Compliance and verification status", "properties": { "kyc_status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "not_required" ], "description": "Know Your Customer verification status" }, "aml_status": { "type": "string", "enum": [ "pending", "in_progress", "cleared", "flagged", "not_required" ], "description": "Anti-Money Laundering check status" } } }, "nickname": { "type": "string", "maxLength": 100, "description": "User-friendly name for the payment means" }, "description": { "type": "string", "maxLength": 500, "description": "Additional description of the payment means" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization" } } }, "relationships": { "$ref": "#/components/schemas/PaymentMeansRelationsShipPost" }, "included": { "$ref": "#/components/schemas/PaymentMeansCreateImcluded" } } } } }, "PaymentMeansRelationsShipPost": { "type": "object", "properties": { "holder": { "type": "object", "description": "Account/payment method owner (required)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "people" ] }, "id": { "type": "string", "description": "UUID of an existing company or person, or temp-id that references an entity defined in the included array" } } } } }, "account_location": { "type": "object", "description": "Bank branch or account location (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing location or temp-id that references a location defined in the included array" } } } } }, "holder_location": { "type": "object", "description": "Account holder's address (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing location or temp-id that references a location defined in the included array" } } } } }, "bank": { "type": "object", "description": "Banking institution (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing company or temp-id that references a company defined in the included array" } } } } }, "intermediary_banks": { "type": "object", "description": "Correspondent/intermediary banks for routing (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing company or temp-id that references a company defined in the included array" } } } } } }, "ultimate_beneficiary": { "type": "object", "description": "Ultimate beneficial owner if different from holder (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "people" ] }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing company or person, or temp-id that references an entity defined in the included array" } } } } }, "created_by": { "type": "object", "description": "User who created this record (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing person or temp-id that references a person defined in the included array" } } } } }, "documents": { "type": "object", "description": "Supporting documents (statements, verifications) (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing document or temp-id that references a document defined in the included array" } } } } } }, "transactions": { "type": "object", "description": "Related transactions using this payment means (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "transaction" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing transaction or temp-id that references a transaction defined in the included array" } } } } } }, "linked_payment_means": { "type": "object", "description": "Related payment methods (e.g., cards linked to account) (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid", "description": "UUID of an existing payment means or temp-id that references a payment means defined in the included array" } } } } } } } }, "PaymentMeansPost": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes", "relationships" ], "properties": { "type": { "type": "string", "const": "payment_means" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/PaymentMeansRelationsShipPost" }, "included": { "$ref": "#/components/schemas/PaymentMeansCreateImcluded" } } } } }, "PaymentMeansCreateImcluded": { "type": "object", "properties": { "holder": { "type": "object", "oneOf": [ { "type": "object", "description": "Account/payment method owner (required)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a holder defined in the included array" }, "attributes": { "$ref": "#/components/schemas/PeopleCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } }, { "type": "object", "description": "Account/payment method owner (required)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a holder defined in the included array" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } ] }, "account_location": { "type": "object", "description": "Locations/addresses associated of the account", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a account location defined in the included array" }, "attributes": { "$ref": "#/components/schemas/LocationCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "holder_location": { "type": "object", "description": "Locations/addresses associated of the holder", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a holder location defined in the included array" }, "attributes": { "$ref": "#/components/schemas/LocationCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "bank": { "type": "object", "description": "bank", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a bank defined in the included array" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } }, "intermediary_banks": { "type": "object", "description": "Correspondent/intermediary banks for routing (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a intermediary bank defined in the included array" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } }, "ultimate_beneficiary": { "type": "object", "oneOf": [ { "type": "object", "description": "Ultimate beneficial owner if different from holder (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a ultimate beneficiary defined in the included array" }, "attributes": { "$ref": "#/components/schemas/PeopleCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } }, { "type": "object", "description": "Parent company of this company", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a ultimate beneficiary defined in the included array" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } ] }, "documents": { "type": "object", "description": "Supporting documents (statements, verifications) (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a document defined in the included array" }, "attributes": { "$ref": "#/components/schemas/DocumentCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "transaction": { "type": "object", "description": "Supporting documents (statements, verifications) (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references a transaction defined in the included array" }, "attributes": { "$ref": "#/components/schemas/TransactionAttributesPost" } }, "required": [ "type", "id", "attributes" ] } } } }, "linked_payment_means": { "type": "object", "description": "Supporting documents (statements, verifications) (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references the linked payment means defined in the included array" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } } } }, "PaymentMeansAttributes": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_details", "account_details", "wallet_details", "cash_details", "check_details", "crypto_details", "other" ], "description": "Type of payment means. See [payment means types](/enums/payment-means) for details." }, "scheme": { "type": "string", "enum": [ "SEPA", "SWIFT", "ACH", "FASTER_PAYMENTS", "VISA", "MASTERCARD", "AMEX", "PAYPAL", "APPLEPAY", "GOOGLEPAY", "STRIPE", "LOCAL", "OTHER" ], "description": "Payment scheme or network. See [scheme types](/enums/sheme-type) for details." }, "status": { "type": "string", "enum": [ "active", "inactive", "pending_verification", "suspended", "expired", "blocked" ], "description": "Current status of the payment means. See [payment means status](/enums/payment-means-status) for details." }, "account_details": { "type": "object", "description": "Bank account details for account_details type", "properties": { "iban": { "type": "string", "description": "International Bank Account Number" }, "bic": { "type": "string", "description": "Bank Identifier Code (SWIFT)" }, "account_number": { "type": "string", "description": "Local account number (alternative to IBAN)" }, "routing_number": { "type": "string", "description": "Bank routing number (US ACH)" }, "currency": { "type": "string", "description": "Currency code (ISO 4217)" } } }, "bank_details": { "type": "object", "description": "Additional bank information", "properties": { "bank_name": { "type": "string", "description": "Name of the bank" }, "bank_code": { "type": "string", "description": "Bank code or identifier" }, "branch_name": { "type": "string", "description": "Bank branch name" }, "branch_code": { "type": "string", "description": "Bank branch code" } } }, "card_details": { "type": "object", "description": "Credit/debit card details for card_details type", "properties": { "masked_pan": { "type": "string", "description": "Masked Primary Account Number (PCI DSS compliant)" }, "brand": { "type": "string", "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "other" ], "description": "Card brand" }, "card_type": { "type": "string", "enum": [ "credit", "debit", "prepaid", "charge" ], "description": "Type of card" }, "expiry_month": { "type": "integer", "description": "Card expiry month" }, "expiry_year": { "type": "integer", "description": "Card expiry year" }, "cardholder_name": { "type": "string", "description": "Name as printed on card" } } }, "digital_wallet": { "type": "object", "description": "Digital wallet details for wallet_details type", "properties": { "provider": { "type": "string", "enum": [ "paypal", "applepay", "googlepay", "stripe", "square", "venmo", "cashapp", "other" ], "description": "Digital wallet provider" }, "wallet_id": { "type": "string", "description": "Wallet identifier (email, phone, etc.)" }, "wallet_type": { "type": "string", "enum": [ "personal", "business", "merchant" ], "description": "Type of wallet account" } } }, "compliance": { "type": "object", "description": "Compliance and verification status", "properties": { "kyc_status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "not_required" ], "description": "Know Your Customer verification status" }, "aml_status": { "type": "string", "enum": [ "pending", "in_progress", "cleared", "flagged", "not_required" ], "description": "Anti-Money Laundering check status" }, "sanctions_check": { "type": "string", "enum": [ "pending", "passed", "failed", "not_required" ], "description": "Sanctions screening status" }, "last_compliance_check": { "type": "string", "format": "date-time", "description": "Last compliance check timestamp" } } }, "metadata": { "type": "object", "description": "System metadata", "properties": { "source": { "type": "string", "enum": [ "api", "dashboard", "import", "connector" ], "description": "How the payment means was created" }, "external_id": { "type": "string", "description": "External system identifier" } } }, "nickname": { "type": "string", "description": "User-friendly name for the payment means" }, "description": { "type": "string", "description": "Additional description of the payment means" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "PaymentMeansCreateAttributes": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "card_details", "account_details", "wallet_details", "..." ], "description": "Type of payment means. See [payment means types](/enums/payment-means) for details." }, "scheme": { "type": "string", "enum": [ "SEPA", "SWIFT", "ACH", "..." ], "description": "Payment scheme or network. See [scheme types](/enums/sheme-type) for details." }, "status": { "type": "string", "enum": [ "active", "inactive", "pending_verification", "suspended", "expired", "blocked" ], "description": "Current status of the payment means. See [payment means status](/enums/payment-means-status) for details." }, "account_details": { "type": "object", "description": "Bank account details for account_details type", "properties": { "iban": { "type": "string", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]+$", "description": "International Bank Account Number" }, "bic": { "type": "string", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$", "description": "Bank Identifier Code (SWIFT)" }, "sort_code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Bank sort code (UK)" }, "account_number": { "type": "string", "description": "Local account number (alternative to IBAN)" }, "routing_number": { "type": "string", "description": "Bank routing number (US ACH)" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency code (ISO 4217)" } } }, "bank_details": { "type": "object", "description": "Additional bank information", "properties": { "bank_name": { "type": "string", "description": "Name of the bank" }, "bank_code": { "type": "string", "description": "Bank code or identifier" }, "branch_name": { "type": "string", "description": "Bank branch name" }, "branch_code": { "type": "string", "description": "Bank branch code" } } }, "card_details": { "type": "object", "description": "Credit/debit card details for card_details type", "properties": { "masked_pan": { "type": "string", "pattern": "^\\*{4}-\\*{4}-\\*{4}-[0-9]{4}$", "description": "Masked Primary Account Number (PCI DSS compliant)" }, "brand": { "type": "string", "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "other" ], "description": "Card brand" }, "card_type": { "type": "string", "enum": [ "credit", "debit", "prepaid", "charge" ], "description": "Type of card" }, "expiry_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Card expiry month" }, "expiry_year": { "type": "integer", "minimum": 2024, "description": "Card expiry year" }, "cardholder_name": { "type": "string", "description": "Name as printed on card" } } }, "digital_wallet": { "type": "object", "description": "Digital wallet details for wallet_details type", "properties": { "provider": { "type": "string", "enum": [ "paypal", "applepay", "googlepay", "stripe", "square", "venmo", "cashapp", "other" ], "description": "Digital wallet provider" }, "wallet_id": { "type": "string", "description": "Wallet identifier (email, phone, etc.)" }, "wallet_type": { "type": "string", "enum": [ "personal", "business", "merchant" ], "description": "Type of wallet account" } } }, "compliance": { "type": "object", "description": "Compliance and verification status", "properties": { "kyc_status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "not_required" ], "description": "Know Your Customer verification status" }, "aml_status": { "type": "string", "enum": [ "pending", "in_progress", "cleared", "flagged", "not_required" ], "description": "Anti-Money Laundering check status" } } }, "nickname": { "type": "string", "maxLength": 100, "description": "User-friendly name for the payment means" }, "description": { "type": "string", "maxLength": 500, "description": "Additional description of the payment means" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization" } } }, "PaymentMeansPostResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansAttributes" }, "relationships": { "type": "object", "properties": { "holder": { "type": "object", "description": "Account/payment method owner", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "people" ] }, "id": { "type": "string", "format": "uuid" } } } } }, "account_location": { "type": "object", "description": "Bank branch or account location", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid" } } } } }, "holder_location": { "type": "object", "description": "Account holder's address", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid" } } } } }, "bank": { "type": "object", "description": "Banking institution", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid" } } } } }, "intermediary_banks": { "type": "object", "description": "Correspondent/intermediary banks for routing", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid" } } } } } }, "ultimate_beneficiary": { "type": "object", "description": "Ultimate beneficial owner if different from holder", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "people" ] }, "id": { "type": "string", "format": "uuid" } } } } }, "created_by": { "type": "object", "description": "User who created this record", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid" } } } } }, "documents": { "type": "object", "description": "Supporting documents (statements, verifications)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid" } } } } } }, "transactions": { "type": "object", "description": "Related transactions using this payment means", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "transaction" }, "id": { "type": "string", "format": "uuid" } } } } } }, "linked_payment_means": { "type": "object", "description": "Related payment methods (e.g., cards linked to account)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "format": "uuid" } } } } } } } }, "included": { "type": "object", "properties": { "holder": { "type": "object", "oneOf": [ { "type": "object", "description": "Account/payment method owner (required)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the person" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } } }, { "type": "object", "description": "Account/payment method owner (required)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } } ] }, "account_location": { "type": "object", "description": "Locations/addresses associated of the account", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "ID of the location" }, "attributes": { "$ref": "#/components/schemas/LocationAttributes" } } } } } }, "holder_location": { "type": "object", "description": "Locations/addresses associated of the holder", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid", "description": "ID of the location" }, "attributes": { "$ref": "#/components/schemas/LocationAttributes" } } } } } }, "bank": { "type": "object", "description": "bank", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } }, "intermediary_banks": { "type": "object", "description": "Correspondent/intermediary banks for routing (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } }, "ultimate_beneficiary": { "type": "object", "oneOf": [ { "type": "object", "description": "Ultimate beneficial owner if different from holder (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the person" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } } }, { "type": "object", "description": "Parent company of this company", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } } ] }, "created_by": { "type": "object", "description": "Person who created this company", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the person" }, "attributes": { "$ref": "#/components/schemas/PeopleAttributes" } } } } }, "documents": { "type": "object", "description": "Supporting documents (statements, verifications) (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document" }, "attributes": { "$ref": "#/components/schemas/DocumentAttributes" } } } } } }, "transaction": { "type": "object", "description": "Supporting documents (statements, verifications) (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document" }, "attributes": { "$ref": "#/components/schemas/TransactionAttributes" } } } } } }, "linked_payment_means": { "type": "object", "description": "Supporting documents (statements, verifications) (optional)", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the document" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansAttributes" } } } } } } } } } } } }, "CompanyIncluded": { "type": "object", "properties": { "type": { "type": "string", "const": "companies" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name" }, "description": { "type": "string", "description": "Company description" } } } } }, "PersonIncluded": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Person's first name" }, "last_name": { "type": "string", "description": "Person's last name" }, "job_title": { "type": "string", "description": "Person's job title" } } } } }, "WorkspaceIncluded": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Workspace name" }, "description": { "type": "string", "description": "Workspace description" } } } } }, "LocationIncluded": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "full_address": { "type": "string", "description": "Complete formatted address" }, "address_line1": { "type": "string", "description": "Primary address line" }, "address_line2": { "type": "string", "description": "Secondary address line" }, "city": { "type": "string", "description": "City name" }, "state": { "type": "string", "description": "State or region" }, "postal_code": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2)" }, "label": { "type": "string", "description": "Location label or type" } } } } }, "DocumentIncluded": { "type": "object", "properties": { "type": { "type": "string", "const": "documents" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Document name" }, "filename": { "type": "string", "description": "Original filename" }, "content_type": { "type": "string", "description": "MIME type of the document" }, "size": { "type": "integer", "description": "File size in bytes" } } } } }, "TransactionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "transaction" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the transaction" }, "attributes": { "$ref": "#/components/schemas/TransactionAttributes" }, "relationships": { "$ref": "#/components/schemas/TransactionRelationshipsPostResponse" }, "included": { "$ref": "#/components/schemas/TransactionIncludedPostResponse" } } } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "current_page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of items per page" }, "total_pages": { "type": "integer", "description": "Total number of pages" }, "total_count": { "type": "integer", "description": "Total number of transactions" }, "has_next_page": { "type": "boolean", "description": "Whether there is a next page" }, "has_previous_page": { "type": "boolean", "description": "Whether there is a previous page" } } }, "filters_applied": { "type": "object", "description": "Summary of filters applied to the query" }, "sort": { "type": "string", "description": "Sort order applied" } } }, "included": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PaymentMeansIncluded" }, { "$ref": "#/components/schemas/CompanyIncluded" }, { "$ref": "#/components/schemas/PersonIncluded" }, { "$ref": "#/components/schemas/WorkspaceIncluded" }, { "$ref": "#/components/schemas/DocumentIncluded" } ] } } } }, "TransactionPatch": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "transaction", "description": "Resource type identifier" }, "attributes": { "$ref": "#/components/schemas/TransactionAttributesPatch" }, "relationships": { "$ref": "#/components/schemas/TransactionRelationshipsPost" }, "included": { "$ref": "#/components/schemas/TransactionIncludedPost" } }, "required": [ "type" ] } }, "required": [ "data" ] }, "TransactionAttributesPatch": { "type": "object", "description": "Partial update attributes for transaction. All fields are optional for PATCH operations.", "properties": { "status": { "type": "string", "enum": [ "pending", "processing", "authorized", "completed", "failed", "rejected", "cancelled", "reversed" ], "description": "Updated transaction status. See [transaction status](/enums/details-banking-transaction-status) for details." }, "executed_at": { "type": "string", "format": "date-time", "description": "Updated execution timestamp in ISO 8601 format" }, "booking_date": { "type": "string", "format": "date", "description": "Updated booking date in YYYY-MM-DD format" }, "value_date": { "type": "string", "format": "date", "description": "Updated value date in YYYY-MM-DD format" }, "settlement_amount": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Updated settlement currency (ISO 4217 code)" }, "amount": { "type": "number", "multipleOf": 0.01, "description": "Updated settlement amount" } } }, "foreign_exchange": { "type": "object", "properties": { "currency_rate": { "type": "string", "description": "Updated exchange rate as string for precision" }, "currency_rate_source": { "type": "string", "description": "Updated source of exchange rate (e.g., ECB, Fed, manual)" }, "currency_pair": { "type": "string", "pattern": "^[A-Z]{3}[A-Z]{3}$", "description": "Updated currency pair (e.g., EURUSD)" } } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "commission", "service", "processing", "transfer", "atm", "overdraft", "monthly", "card", "other" ], "description": "Updated fee type" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Updated fee currency" }, "amount": { "type": "number", "multipleOf": 0.01, "description": "Updated fee amount" }, "description": { "type": "string", "description": "Updated fee description" } } } }, "remittance_information": { "type": "object", "properties": { "unstructured": { "type": "array", "items": { "type": "string" }, "description": "Updated unstructured remittance information" }, "structured": { "type": "object", "properties": { "reference": { "type": "string", "description": "Updated payment reference" }, "reference_type": { "type": "string", "enum": [ "SCOR", "CBFF", "REMI", "RADM" ], "description": "Updated reference type" }, "reference_issuer": { "type": "string", "description": "Updated reference issuer" }, "creditor_reference_information": { "type": "object", "properties": { "reference": { "type": "string", "description": "Updated creditor reference" }, "reference_type": { "type": "string", "description": "Updated creditor reference type" }, "reference_issuer": { "type": "string", "description": "Updated creditor reference issuer" } } } } } } }, "external_ids": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Updated external system identifiers" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Updated additional metadata" } } }, "ConnectorPost": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "connector", "description": "Resource type identifier" }, "attributes": { "$ref": "#/components/schemas/ConnectorAttributesPost" }, "relationships": { "$ref": "#/components/schemas/ConnectorRelationshipsPost" }, "included": { "$ref": "#/components/schemas/ConnectorIncludedPost" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] }, "ConnectorPostResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "connector" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the created connector", "example": "550e8400-e29b-41d4-a716-446655440000" }, "attributes": { "$ref": "#/components/schemas/ConnectorAttributesPostResponse" }, "relationships": { "$ref": "#/components/schemas/ConnectorRelationshipsPostResponse" }, "included": { "$ref": "#/components/schemas/ConnectorIncludedPostResponse" } } } } }, "ConnectorPatch": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "connector", "description": "Resource type identifier" }, "attributes": { "$ref": "#/components/schemas/ConnectorAttributesPatch" }, "relationships": { "$ref": "#/components/schemas/ConnectorRelationshipsPost" }, "included": { "$ref": "#/components/schemas/ConnectorIncludedPost" } } } } }, "ConnectorAttributesPost": { "type": "object", "properties": { "slug": { "type": "string", "maxLength": 255, "pattern": "^[a-z0-9_-]+$", "description": "Connector slug used in URLs (system generated if not provided)", "example": "salesforce" }, "name": { "type": "string", "maxLength": 255, "description": "Connector name", "example": "Salesforce" }, "description": { "type": "string", "maxLength": 1000, "description": "Description of the connector", "example": "Connects to Salesforce CRM for sync." }, "category": { "type": "string", "enum": [ "database", "data_warehouse", "file", "..." ], "description": "Category type. See [all available categories](/enums/category-connector) for complete list.", "example": "api" }, "direction": { "type": "string", "description": "Data flow direction capability", "enum": [ "import", "export" ], "example": "import" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Grouping/search tags", "example": [ "crm", "cloud", "sync" ] }, "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$", "description": "Connector version", "example": "2.1.0" }, "data_quality": { "type": "object", "properties": { "imported_fields": { "type": "array", "items": { "type": "string", "enum": [ "invoice", "company", "people", [ "..." ] ] }, "description": "Category connector. See [all available categories](/enums/category-connector) for complete list.", "example": [ "invoice", "company", "people" ] }, "last_synced": { "type": "string", "format": "date-time", "description": "Timestamp of last sync", "example": "2025-06-20T09:00:00Z" } } }, "redirect_url": { "type": "string", "format": "uri", "description": "URL to redirect customers after onboarding flow", "example": "https://app.well.com/connectors/salesforce/success" }, "state": { "type": "string", "description": "State included in the redirect URL", "example": "active" } }, "required": [ "name", "slug", "description", "category", "direction" ] }, "ConnectorAttributesPostResponse": { "type": "object", "properties": { "slug": { "type": "string", "maxLength": 255, "pattern": "^[a-z0-9_-]+$", "description": "Connector slug used in URLs (system generated if not provided)", "example": "salesforce" }, "name": { "type": "string", "maxLength": 255, "description": "Connector name", "example": "Salesforce" }, "description": { "type": "string", "maxLength": 1000, "description": "Description of the connector", "example": "Connects to Salesforce CRM for sync." }, "category": { "type": "string", "enum": [ "database", "..." ], "description": "Integration category. See [all available categories](/enums/category-connector) for complete list.", "example": "api" }, "direction": { "type": "string", "enum": [ "import", "export", "both" ], "description": "Data flow direction capability", "example": "import" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Grouping/search tags", "example": [ "crm", "cloud", "sync" ] }, "data_quality": { "type": "object", "properties": { "imported_fields": { "type": "array", "items": { "type": "string", "enum": [ "invoice", "company", "people" ] }, "description": "Category connector. See [all available categories](/enums/category-connector) for complete list.", "example": [ "invoice", "company", "people" ] }, "last_synced": { "type": "string", "format": "date-time", "description": "Timestamp of last sync", "example": "2025-06-20T09:00:00Z" } } }, "redirect_url": { "type": "string", "format": "uri", "description": "URL to redirect customers after onboarding flow", "example": "https://app.well.com/connectors/salesforce/success" }, "state": { "type": "string", "description": "State included in the redirect URL", "example": "active" }, "status": { "type": "string", "enum": [ "active", "beta", "deprecated" ], "description": "Lifecycle status (system managed)", "example": "active" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp", "example": "2025-10-07T14:30:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2025-10-07T14:30:00.000Z" } } }, "ConnectorIncludedPost": { "type": "object", "properties": { "published_by": { "type": "object", "description": "Workspaces associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references to the publisher defined in the included array" }, "attributes": { "$ref": "#/components/schemas/WorkspaceCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "logo": { "type": "object", "description": "Media files associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "Temp-id that references to the logo defined in the included array" }, "attributes": { "$ref": "#/components/schemas/MediaAttributesJson" } }, "required": [ "type", "id", "attributes" ] } } } } } }, "ConnectorRelationshipsPost": { "type": "object", "properties": { "published_by": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "description": "UUID of an existing workspace or temp-id that references a workspace defined in the included array", "example": "airbyte" } }, "required": [ "type", "id" ] } } }, "logo": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "description": "UUID of an existing logo or temp-id that references a logo defined in the included array", "example": "media3" } }, "required": [ "type", "id" ] } } } } }, "ConnectorIncludedPostResponse": { "type": "object", "description": "Object containing included resources referenced in relationships, organized by resource type. These are the actual created/linked resources with real UUIDs.", "properties": { "published_by": { "type": "object", "description": "Workspaces associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace" }, "attributes": { "$ref": "#/components/schemas/WorkspaceCreateAttributes" } } } } } }, "media": { "type": "object", "description": "Media files associated with this company", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the media" }, "attributes": { "$ref": "#/components/schemas/MediaAttributes" } } } } } } } }, "ConnectorRelationshipsPostResponse": { "type": "object", "properties": { "published_by": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workspace that published this connector", "example": "550e8400-e29b-41d4-a716-446655440001" } } } } }, "logo": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the logo media", "example": "550e8400-e29b-41d4-a716-446655440010" } } } } } } }, "MediaReference": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "Media UUID" }, "attributes": { "type": "object", "properties": { "file_name": { "type": "string", "description": "File name" }, "content_type": { "type": "string", "description": "MIME type" }, "file_size": { "type": "integer", "description": "File size in bytes" } } } } }, "ConnectorListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "connector" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the connector", "example": "550e8400-e29b-41d4-a716-446655440000" }, "attributes": { "$ref": "#/components/schemas/ConnectorAttributesPostResponse" }, "relationships": { "$ref": "#/components/schemas/ConnectorRelationshipsPostResponse" }, "included": { "$ref": "#/components/schemas/ConnectorIncludedPostResponse" } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number", "example": 1 }, "limit": { "type": "integer", "description": "Number of items per page", "example": 25 }, "total": { "type": "integer", "description": "Total number of items", "example": 100 }, "total_pages": { "type": "integer", "description": "Total number of pages", "example": 4 } } } } }, "ConnectorAttributesPatch": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL-friendly identifier for the connector", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "example": "salesforce-updated" }, "name": { "type": "string", "description": "Human-readable name of the connector", "example": "Updated Salesforce CRM Integration" }, "description": { "type": "string", "description": "Detailed description of the connector functionality", "example": "Enhanced Salesforce CRM connector with new sync capabilities" }, "category": { "type": "string", "enum": [ "database", "data_warehouse", "..." ], "description": "Category classification for the connector. See [all available categories](/enums/category-connector) for complete list.", "example": "crm" }, "direction": { "type": "string", "enum": [ "import", "export", "both" ], "description": "Data flow direction capability of the connector", "example": "both" }, "imported_fields": { "type": "array", "items": { "type": "string", "enum": [ "invoice", "company", "people" ] }, "description": "List of data types/fields that this connector can import. See [imported resources](/enums/connector-data-quality) for available options.", "example": [ "invoice", "company", "people" ] }, "data_quality": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Quality assessment of data provided by this connector", "example": "high" } } }, "ConnectorRelationshipsPatch": { "type": "object", "properties": { "published_by": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "organization" }, "id": { "type": "string", "description": "Organization identifier that published this connector" } } } } }, "category": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "category" }, "id": { "type": "string", "description": "Category identifier" } } } } }, "media": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "media" }, "id": { "type": "string", "format": "uuid", "description": "Media asset UUID (logo, icon, etc.)" } } } } } } }, "UnauthorizedError": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED", "description": "Error code identifier" }, "status": { "type": "integer", "example": 401, "description": "HTTP status code" }, "title": { "type": "string", "example": "Unauthorized", "description": "Error title" }, "message": { "type": "string", "example": "You are not authorized to access this resource", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] }, "InvoiceCreateAttributes": { "type": "object", "properties": { "reference_number": { "type": "string", "description": "Unique reference number for the invoice", "example": "INV-2025-001" }, "document_type_code": { "type": "string", "description": "Standard document type code (UN/EDIFACT)", "example": "380" }, "issue_date": { "type": "string", "format": "date", "description": "Date when the invoice was issued", "example": "2025-01-15" }, "due_date": { "type": "string", "format": "date", "description": "Payment due date", "example": "2025-02-15" }, "local_currency": { "type": "string", "description": "Currency code for the invoice (ISO 4217)", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "local_totals": { "type": "object", "properties": { "items_total": { "type": "number", "description": "Subtotal before taxes or discounts", "example": 2500 }, "tax_total": { "type": "number", "description": "Total tax amount", "default": 0, "example": 0 }, "grand_total": { "type": "number", "description": "Total after tax/discounts", "example": 50 } }, "required": [ "items_total" ], "description": "Financial totals for the invoice" }, "terms": { "type": "string", "example": "Net 30", "description": "Contractual payment terms" }, "billing_context": { "type": "string", "description": "Billing context identifier", "example": "subscription" }, "payment_status": { "type": "object", "properties": { "paid": { "type": "boolean", "description": "Whether the invoice has been paid", "example": true }, "local_amount_paid": { "type": "number", "description": "Amount paid in local currency", "example": 3000 }, "local_amount_remaining": { "type": "number", "description": "Remaining unpaid amount in local currency", "example": 0 } }, "required": [ "paid" ], "description": "Payment status and amounts" }, "description": { "type": "string", "description": "Invoice description or notes", "example": "Professional services invoice for January 2025" } }, "required": [ "reference_number", "document_type_code", "local_currency", "local_totals" ], "description": "Invoice attributes and data" }, "InvoiceIncludedPost": { "type": "object", "properties": { "issuer": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "example": "company-2", "description": "Temp-id that references a company in the relationships" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "receiver": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "example": "company-2", "description": "Temp-id that references a company in the relationships" }, "attributes": { "$ref": "#/components/schemas/CompanyCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "payment_means": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "example": "pm-1", "description": "Temp-id that references a payment means in the relationships" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "invoice_items": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice_item" }, "id": { "type": "string", "example": "item-1", "description": "Temp-id that references an invoice item in the relationships" }, "attributes": { "$ref": "#/components/schemas/InvoiceItemsCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "example": "doc-1", "description": "Temp-id that references a document in the relationships" }, "attributes": { "$ref": "#/components/schemas/DocumentCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } }, "people": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "id": { "type": "string", "example": "person-1", "description": "Temp-id that references a person in the relationships" }, "attributes": { "$ref": "#/components/schemas/PeopleCreateAttributes" } }, "required": [ "type", "id", "attributes" ] } } } } } }, "InvoiceRelationsShipPost": { "type": "object", "properties": { "issuer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "example": "company-uuid", "description": "UUID of an existing company or temp-id that references a company defined in the included array" } } } }, "required": [ "data" ], "description": "Company issuing the invoice" }, "receiver": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "example": "company-uuid", "description": "UUID of an existing company or temp-id that references a company defined in the included array" } } } }, "required": [ "data" ], "description": "Company receiving the invoice" }, "payment_means": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "example": "pm_1", "description": "UUID of an existing payment means or temp-id that references a payment means defined in the included array" } } } } }, "description": "Associated payment methods" }, "invoice_items": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice_item" }, "id": { "type": "string", "example": "pm_1", "description": "UUID of an existing invoice item or temp-id that references an invoice item defined in the included array" } } } } }, "description": "Line items included in the invoice" }, "documents": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "example": "doc_original_invoice", "description": "UUID of an existing document or temp-id that references a document defined in the included array" } } } } }, "description": "Supporting documents attached to the invoice" }, "people": { "$ref": "#/components/schemas/WorkspaceRelationRequest" } }, "required": [ "issuer", "receiver" ], "description": "Relationships with other resources" }, "InvoicePost": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invoice" ], "description": "Resource type identifier" }, "attributes": { "$ref": "#/components/schemas/InvoiceCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/InvoiceRelationsShipPost" }, "included": { "$ref": "#/components/schemas/InvoiceIncludedPost" } }, "required": [ "type", "attributes", "relationships" ] } }, "required": [ "data" ], "description": "Schema for creating a new invoice" }, "InvoicePatch": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invoice" ], "description": "Resource type identifier" }, "attributes": { "type": "object", "properties": { "reference_number": { "type": "string", "description": "Unique reference number for the invoice", "example": "INV-2025-001" }, "document_type_code": { "type": "string", "description": "Standard document type code (UN/EDIFACT)", "example": "380" }, "issue_date": { "type": "string", "format": "date", "description": "Date when the invoice was issued", "example": "2025-01-15" }, "due_date": { "type": "string", "format": "date", "description": "Payment due date", "example": "2025-02-15" }, "local_currency": { "type": "string", "description": "Currency code for the invoice (ISO 4217)", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "local_totals": { "type": "object", "properties": { "items_total": { "type": "number", "description": "Subtotal before taxes or discounts", "example": 2500 }, "tax_total": { "type": "number", "description": "Total tax amount", "default": 0, "example": 0 }, "grand_total": { "type": "number", "description": "Total after tax/discounts", "example": 50 } }, "required": [ "items_total" ], "description": "Financial totals for the invoice" }, "terms": { "type": "string", "example": "Net 30", "description": "Contractual payment terms" }, "billing_context": { "type": "string", "description": "Billing context identifier", "example": "subscription" }, "payment_status": { "type": "object", "properties": { "paid": { "type": "boolean", "description": "Whether the invoice has been paid", "example": true }, "local_amount_paid": { "type": "number", "description": "Amount paid in local currency", "example": 3000 }, "local_amount_remaining": { "type": "number", "description": "Remaining unpaid amount in local currency", "example": 0 } }, "required": [ "paid" ], "description": "Payment status and amounts" }, "description": { "type": "string", "description": "Invoice description or notes", "example": "Professional services invoice for January 2025" } }, "required": [ "reference_number", "document_type_code", "local_currency", "local_totals" ], "description": "Invoice attributes and data" }, "relationships": { "$ref": "#/components/schemas/InvoiceRelationsShipPost" }, "included": { "$ref": "#/components/schemas/InvoiceIncludedPost" } }, "required": [ "type" ] } }, "required": [ "data" ], "description": "Schema for creating a new invoice" }, "PersonRelationshipItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "people" ] }, "id": { "type": "string", "description": "Person ID" }, "attributes": { "$ref": "#/components/schemas/PersonAttributes" } } }, "PersonRelationship": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonRelationshipItem" } } } }, "CompanyRelationshipItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "id": { "type": "string", "description": "Company ID" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } }, "CompanyRelationship": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyRelationshipItem" } } } }, "WorkspaceRelationshipItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "workspace" ] }, "id": { "type": "string", "description": "Workspace ID" }, "attributes": { "$ref": "#/components/schemas/WorkspaceAttributes" } } }, "WorkspaceRelationship": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceRelationshipItem" } } } }, "WebLinkCreateAttributes": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "website", "linkedin", "x", "github" ], "description": "Web platform type" }, "url": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Full profile URL" } }, "required": [ "url" ] }, "WebLinkCreateRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "web_link" }, "attributes": { "$ref": "#/components/schemas/WebLinkCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/SimpleRelationships" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] }, "WebLinkAttributes": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "website", "linkedin", "x", "github" ], "description": "Web platform type" }, "url": { "type": "string", "description": "Full profile URL" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the web link was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the web link was updated" } } }, "WebLinkCreateResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "example": "web_link" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/WebLinkAttributes" }, "relationships": { "type": "object", "properties": { "persons": { "$ref": "#/components/schemas/PersonRelationship" }, "companies": { "$ref": "#/components/schemas/CompanyRelationship" }, "workspaces": { "$ref": "#/components/schemas/WorkspaceRelationship" } } } } } } }, "LocationCreateRequest": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "location" }, "attributes": { "$ref": "#/components/schemas/LocationCreateAttributes" }, "relationships": { "$ref": "#/components/schemas/SimpleRelationships" } }, "required": [ "type", "attributes" ] } }, "required": [ "data" ] }, "LocationCreateAttributes": { "type": "object", "properties": { "address_line1": { "type": "string", "description": "Primary address line" }, "address_line2": { "type": "string", "description": "Secondary address line (optional)" }, "city": { "type": "string", "description": "City name" }, "region": { "type": "string", "description": "State, province, or region" }, "postal_code": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Two-letter ISO country code (e.g., 'US', 'GB')" }, "latitude": { "type": "number", "format": "float", "description": "Geographic latitude coordinate" }, "longitude": { "type": "number", "format": "float", "description": "Geographic longitude coordinate" }, "is_primary": { "type": "boolean", "description": "Whether this is the primary location", "default": false }, "is_registered": { "type": "boolean", "description": "Whether this is a registered business address", "default": false }, "label": { "type": "string", "enum": [ "work", "personal", "other", "..." ], "description": "Email label type. See [all available labels](/enums/label) for complete list." } }, "required": [ "address_line1", "country" ] }, "LocationCreateResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "example": "location" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "$ref": "#/components/schemas/LocationAttributes" }, "relationships": { "type": "object", "properties": { "persons": { "$ref": "#/components/schemas/PersonRelationship" }, "companies": { "$ref": "#/components/schemas/CompanyRelationship" }, "workspaces": { "$ref": "#/components/schemas/WorkspaceRelationship" } } } } } } }, "LocationAttributes": { "type": "object", "properties": { "full_address": { "type": "string", "description": "Complete formatted address" }, "address_line1": { "type": "string", "description": "Primary address line" }, "address_line2": { "type": "string", "description": "Secondary address line" }, "city": { "type": "string", "description": "City name" }, "region": { "type": "string", "description": "State, province, or region" }, "postal_code": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Two-letter ISO country code" }, "latitude": { "type": "number", "format": "float", "description": "Geographic latitude coordinate" }, "longitude": { "type": "number", "format": "float", "description": "Geographic longitude coordinate" }, "is_primary": { "type": "boolean", "description": "Whether this is the primary location" }, "is_registered": { "type": "boolean", "description": "Whether this is a registered business address" }, "label": { "type": "string", "description": "Custom label for the location" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the location was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the location was last updated" } } }, "InvoiceResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invoice" ], "description": "Resource type identifier" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created invoice", "example": "invoice_550e8400-e29b-41d4-a716-446655440000" }, "attributes": { "type": "object", "properties": { "reference_number": { "type": "string", "description": "Unique reference number for the invoice", "example": "INV-2025-001" }, "document_type": { "type": "string", "description": "Type of invoice document", "example": "commercial_invoice" }, "document_type_code": { "type": "string", "description": "Standard document type code", "example": "380" }, "issue_date": { "type": "string", "format": "date", "description": "Date when the invoice was issued", "example": "2025-01-15" }, "due_date": { "type": "string", "format": "date", "description": "Payment due date", "example": "2025-02-15" }, "local_currency": { "type": "string", "description": "Currency code for the invoice", "example": "EUR" }, "local_totals": { "type": "object", "properties": { "subtotal": { "type": "string", "description": "Subtotal before taxes and discounts", "example": "1000.00" }, "tax_total": { "type": "string", "description": "Total tax amount", "example": "200.00" }, "total_amount": { "type": "string", "description": "Final total amount", "example": "1200.00" } } }, "terms": { "type": "string", "description": "Contractual payment terms" }, "billing_context": { "type": "string", "description": "Billing context identifier", "example": "subscription" }, "payment_status": { "type": "object", "properties": { "paid": { "type": "boolean" }, "amount_paid": { "type": "number" }, "amount_remaining": { "type": "number" } } }, "status": { "type": "string", "enum": [ "draft", "sent", "viewed", "accepted", "rejected", "cancelled" ], "description": "Invoice lifecycle status", "example": "draft" }, "description": { "type": "string", "description": "Invoice description or notes", "example": "Professional services invoice for January 2025" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the invoice was created", "example": "2025-01-15T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the invoice was last updated", "example": "2025-01-15T10:30:00Z" } } }, "relationships": { "type": "object", "properties": { "issuer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "example": "company-uuid", "description": "uuid of company" } } } }, "description": "Company issuing the invoice" }, "receiver": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "example": "company-uuid", "description": "uuid of company" } } } }, "description": "Company receiving the invoice" }, "payment_means": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "example": "pm_1" } } } } }, "description": "Associated payment methods" }, "invoice_items": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_means" }, "id": { "type": "string", "example": "pm_1" } } } } }, "description": "Line items included in the invoice" }, "document": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "document" }, "id": { "type": "string", "example": "document-uuid", "description": "uuid of document" } } } }, "description": "Supporting document attached to the invoice" }, "people": { "$ref": "#/components/schemas/PersonsRelationshipData" } }, "description": "Relationships with other resources" }, "included": { "type": "object", "properties": { "documents": { "type": "object", "description": "Supporting document attached to the invoice", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/DocumentAttributes" } } } } }, "invoice_items": { "type": "object", "description": "Correspondent/intermediary banks for routing (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/InvoiceItemsAttributes" } } } } }, "payment_means": { "type": "object", "description": "Correspondent/intermediary banks for routing (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/PaymentMeansAttributes" } } } } }, "receiver": { "type": "object", "description": "Correspondent/intermediary banks for routing (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } }, "issuer": { "type": "object", "description": "Correspondent/intermediary banks for routing (optional)", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "const": "company" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the parent company" }, "attributes": { "$ref": "#/components/schemas/CompanyAttributes" } } } } } } } } } }, "description": "Response schema for successfully created invoice" }, "WorkspaceAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Workspace name" }, "desription": { "type": "string", "description": "Workspace description" }, "external_workspace_id": { "type": "string", "format": "uuid", "description": "external workspace id" }, "avatar_color": { "type": "string", "format": "colors", "description": "Color of the avatar" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workspace was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workspace was last updated" } } } }, "parameters": { "AuthorizationHeader": { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer token for authentication" } }, "responses": { "InvoiceNotFound": { "description": "Invoice not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "invoice_not_found" }, "message": { "type": "string", "example": "Invoice not found" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "invoice_not_found", "message": "Invoice not found" } } } } }, "PersonNotFound": { "description": "Person not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "PERSON_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Person Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested person could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "WebLinkNotFound": { "description": "Web link not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "WEB_LINK_NOT_FOUND" }, "status": { "type": "integer", "example": 404 }, "title": { "type": "string", "example": "Web Link Not Found" }, "message": { "type": "string", "example": "The requested web link could not be found" } } } } } }, "CompanyNotFound": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "COMPANY_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Company Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested company could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "CompanyOrPersonNotFound": { "description": "Company or person not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "COMPANY_OR_PERSON_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Company or Person Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested company or one of the specified people could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "MembershipNotFound": { "description": "Membership not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "MEMBERSHIP_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Membership Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested membership could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "ApiKeyNotFound": { "description": "API Key not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "API_KEY_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "API Key Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested API key could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "WebhookNotFound": { "description": "Webhook subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "WEBHOOK_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Webhook Subscription Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested webhook subscription could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "WorkspaceNotFound": { "description": "Workspace not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "WORKSPACE_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Workspace Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested workspace could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "DocumentNotFound": { "description": "Document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "DOCUMENT_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Document Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested document could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "MediaNotFound": { "description": "Media not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "MEDIA_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Media Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested media could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } }, "LocationNotFound": { "description": "Location not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "LOCATION_NOT_FOUND", "description": "Error code identifier" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "title": { "type": "string", "example": "Location Not Found", "description": "Error title" }, "message": { "type": "string", "example": "The requested location could not be found", "description": "Detailed error message" }, "meta": { "type": "object", "properties": { "log_id": { "type": "string", "format": "uuid", "example": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b", "description": "Unique identifier for tracking this error in logs" } }, "required": [ "log_id" ] } }, "required": [ "code", "status", "title", "message", "meta" ] } } } } } } }