![\"Import](\"https://cdn.vat4u.com/media/import-api.svg\")
VAT4U API allows you to easily integrate an external system, such as Travel expense management tool of your company, or ERP system.
VAT4U API exposes a set of endpoints to create a single expense or initiate mass data import to the VAT4U platform.
API is organized around REST protocol.
VAT4U API endpoints by default expect JSON formatted body, with Content-Type: application/json header, if not explicitly specified otherwise.
Each API endpoint requires Authorization Bearer token inside Authorization header. Auth token should be retrieved from Authentication /auth/token endpoint, and used inside Authorization header for all API requests, in form of Authorization: Bearer TOKEN_HERE
VAT4U API response is organized around standard HTTP response codes, returning 200 OK code for all successful GET requests, 201 Created for synchronous POST requests, and 202 Accepted for asynchronous POST requests.
Requests ending with Errors return appropriate HTTP response codes, such as 400 Bad Request for unexpected input parameters, 401 Unauthorized for unauthorized access attempts, and 403 Forbidden for lack of permissions for Authenticated user.
Unsuccessful GET requests failing to locate requested objects will result in 404 Not found HTTP response code.500 Internal Server Error is returned in case of unexpected server-side failure.
For all endpoints successful response will return an object with the following structure:
\n{\n \"status\": \"success\",\n \"data\": { /* underlying object properties */ }\n}\n\nRequest resulting in error response will have a response object with the following structure:
\n{\n \"status\": \"error\",\n \"error\": {\n \"code\": \"ERROR_CODE\",\n \"message\": \"User friendly error message\"\n }\n}\n\nRate limiting is based on 'Leaky Bucket' implementation.
When a client hits budget limit 429 Too many requests HTTP response is sent.
Post user login credentials to /auth/token endpoint to get Access token.
\n","urlObject":{"path":["v1","auth","token"],"host":["https://api.vat4u.com"],"query":[],"variable":[]}},"response":[{"id":"ea005645-be7e-4887-b51f-5637edd16e00","name":"Successfully retrieve access token","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n\t\"username\": \"{{username}}\",\n\t\"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/auth/token"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Server","value":"nginx/1.27.4"},{"key":"Date","value":"Fri, 17 Oct 2025 14:56:30 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Set-Cookie","value":"ci_session=plvhfsotl4uh7s4qvrakfbromorl76s4; expires=Fri, 17 Oct 2025 15:26:30 GMT; Max-Age=1800; path=/; domain=app.vat4u.local; secure; HttpOnly; SameSite=Lax"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method"},{"key":"Access-Control-Allow-Methods","value":"GET, POST"}],"cookie":[],"responseTime":null,"body":"{\n \"accessToken\": \"...0eXAiOiJKV1QiOiJIUzI1NiJ9...\",\n \"tokenType\": \"Bearer\",\n \"issuedAt\": 1760712990,\n \"expiresIn\": 3600\n}"},{"id":"c1cdd7d1-69e7-4be5-84d0-76daacf8e4fb","name":"Failed authentication","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n\t\"username\": \"user@vat4u.com\",\n\t\"password\": \"wrong-password\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/auth/token"},"status":"Forbidden","code":403,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"3b0a824c-4ce8-428c-b857-bf3434bf6e5e"}],"id":"960c86dd-22dd-45f7-9936-aae65b1c2ea5","description":"Authentication and Authorization section of API allows you to authenticate users with the VAT4U platform and retrieve AccessToken to be used for subsequent API requests.
\nAccessToken has lifetime specified in response object of /auth/token endpoint.
POST method to /expenses endpoint will initiate the creation of an expense entry. Depending on the outcome of this API procedure success or failure will be returned from the subsystem.
\nA successful call to the endpoint will result in 201 Created status, with an underlying result object.
\nExpenseDocument objects have the following schema:
When it comes to sending documents to VAT4U there are two options:
\nSpecify list of documents with filename and Base64 data within documents property of the request. With this option only a single request is sent to VAT4U API and multiple documents upload is supported. At the moment only PDF files are allowed with this method.
\n[DEPRICATED - for existing integrations only] Use parameter expectDocument to announce to VAT4U that it should return a signed URL which will be used with the second request to supply the specific document. In this case two subsequent requests are necessary to supply both data and document. Only single document is supported with this method. Only PDF document is supported at the moment.
Option 1 has higher priority and option 2 is only considered if no documents property is present in the first request.
If documents array is not present in the request, and expectDocument property is set to true, the system will return a temporary URL inside response object documentLocation property documentLocation.url.
Invoice document (electronic document, scan, or picture) can be uploaded to this temporary URL using a PUT request. This request should include a document as a Binary request body.
Other types of payload (e.g. Base64) will also return code 200 but documents will not be accepted for processing, opposite to the first option (single request with data and documents array) when sending documents is only possible in base64 representation. The returned URL will expire in period specified under doocumentLocation.expiresIn property. Value is integer with unit of seconds.
![](\"https://cdn.vat4u.com/media/single-expense.svg\")
\n\nitem object properties)When supplied together, any of two value indicators (gross + net, gross + vat, net + vat) are threatened with higher priority and system VAT rates are overruled by supplied values.
\nTo let the system calculate amounts based on system stored VAT rates, supply only one of the amount parameters. Either grossAmount, netAmotun, or vatAmount.
\nParameter category needs to be part of the mapping supplied at the Expense level
\nvendor object properties)optionalFields parameter)Each expense can define one or multiple optional fields. List of allowed optional fields is provided below. Optional fields parameter is of type array, containing single objects with properties name and value. Name should always correspond to one of the valid optional field values listed below.
Valid options for TransactionType are [\"Travel expenses\", \"Account payable\", \"Importation\", \"Other\"].
Valid options for ErpGLAccountDebitOrCredit are [\"Debit\", \"Credit\"]
Valid options for PaymentFlow are [Travel Reimbursement, Travel Direct Payment, Other]. This field plays improtant role for Canadian TAX reporting when using Simplified ITC/ITR calculation method. Different factors apply when payment flow is Reimboursement to the employee and Direct company payment to supplier.
Fields with values of type date should contain valid dates in the listed format.
\nExample:optionalFields : [{\"name\" : \"CostCenter\", \"value\" : \"Marketing\"}, {\"name\": \"ErpTemBookingDate\", \"value\": \"2021-03-17\"}]
Field LegalEntityCode is specifically used for the expense mapping together with companiesMappingId when option to send expenses to multiple entities from one single connection is used. In this scenario initially we collect all the entity codes (or names) from the integrator. Based on this codes initial setup is done on VAT4U side and companiesMappingId is generated for this setup. Integrator then commits on sending both companyId, companiesMappingId and LegalEntityCode Optional field which will contain one of the previously defined entity codes from an external system.
To start expense post-processing you should include additional parameters in the actions object indicating the type of actions that should be taken.
Currently, we offer three post-processing options:
Compliance Check - optional - if set to TRUE VAT4U will start the Compliance check process.
\nData Verification - optional - if set to TRUE VAT4U will start the Data Verification check process.
\nSmartAI Data Retrieval - optional - can be set to \"process\" or \"apply\". If set to `process` VAT4U will start and process the expense with SmartAI but will not automatically apply the identified data to the expense. In this case after processing is finished, SmartAI data will be available as a separate Single expense response property. If set to `apply`, immediately after processing the expense data will be updated with the SmartAI identified fields (e.g. Invoice number, date, country of refund, vendor information, etc.) If you wish choose to apply only a portion of expense details, you can specify the desired fields in the fields array inside the actions object. Each field is an object of the following structure: {\"name\": \"fieldName\", \"method\": \"applyMethod\"}. The fieldName must be of one of the following values: ['date', 'number', 'vendorName', 'streetName', 'streetNumber', 'zipCode', 'city', 'vatNumber', 'taxNumber', 'totalNetAmount', 'totalVatAmount', 'totalGrossAmount', 'currency', 'country', 'vendorCountry', 'province', 'mainCategory'], while the method allowed values are: ['use-when-identified' (always apply), 'use-when-empty' (apply only if the original field data is empty), 'use-when-empty-or-diff' (apply only if the original field data is empty or different)]. Don't specify the fields array or leave it empty to apply all of the SmartAI data to the expense.
Note: Each action is started as an asynchronous process. You can pull the expense by ID to fetch the latest status and expense properties, or subscribe to our Webhooks and get notified when expense status or properties change.
\nSubscribing to a webhooks is recommended solution to minimise the API calls overhead and have the fastest update times. Webhook can be configured on the account level (service provider) or a single claimant level.
\nRead more about webhooks in our Help center article.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}},"urlObject":{"path":["v1","expenses"],"host":["https://api.vat4u.com"],"query":[],"variable":[]}},"response":[{"id":"2d2fdfbd-5afa-4909-9312-4b43330d80fd","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"companyId\": \"{{companyKey}}\",\n \"expenseDate\": \"18/05/2024\",\n \"expenseNumber\": \"APPI-TEST-29411\",\n \"countryOfExpense\": \"DE\",\n \"currencyOfExpense\": \"EUR\",\n \"rejectOutOfScopeCountry\": false,\n \"expenseType\": \"purchase\",\n \"acceptUnknownCategory\": true,\n \"items\": [\n {\n \"grossAmount\": 124.11,\n \"category\": \"Accommodation\",\n \"description\": \"3 night stay\"\n },\n {\n \"grossAmount\": 19.00,\n \"category\": \"Breakfast\",\n \"description\": \"\"\n }\n ],\n \"vendor\": {\n \"name\": \"Motel One\",\n \"vatNumber\": \"DE123491011\",\n \"taxNumber\": \"\",\n \"streetName\": \"Immermannstrasse\",\n \"streetNumber\": \"54\",\n \"streetOther\": \"\",\n \"city\": \"Dusseldorf\",\n \"zipCode\": \"40210\",\n \"countryCode\": \"DE\"\n },\n \"expectDocument\": {\n \"contentType\": \"application/pdf\"\n },\n \"documents\": [\n {\n \"fileName\": \"test.pdf\",\n \"base64\": \"__base64 encode document content (pdf/jpg/png/tiff)__\"\n }\n ],\n \"autoClean\": true,\n \"optionalFields\": [\n {\n \"name\": \"TransactionType\",\n \"value\": \"Travel expenses\"\n },\n {\n \"name\": \"TemTransactionIdentifier\",\n \"value\": \"019273714123\"\n },\n {\n \"name\": \"LegalEntityCode\",\n \"value\": \"LX81623\"\n }\n ],\n \"actions\": {\n \"complianceCheck\": true,\n \"dataVerification\": true,\n \"smartAi\": \"apply\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/expenses"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Server","value":"nginx/1.27.4"},{"key":"Date","value":"Mon, 27 Oct 2025 00:04:20 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Set-Cookie","value":"ci_session=ut8guh9s0d4nkclncvt77hr963cog9vu; expires=Mon, 27 Oct 2025 00:34:11 GMT; Max-Age=1800; path=/; domain=app.vat4u.local; secure; HttpOnly; SameSite=Lax"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method"},{"key":"Access-Control-Allow-Methods","value":"GET, POST"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"X-RateLimit-Reset","value":"1761523500"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": {\n \"expenseId\": 151946752412,\n \"expenseKey\": 151946752412,\n \"documentLocation\": null,\n \"expenseData\": {\n \"id\": 151946752412,\n \"parentId\": null,\n \"company\": {\n \"id\": 2,\n \"legalName\": \"VAT4U GmbH\"\n },\n \"date\": \"2024-05-18\",\n \"number\": \"APPI-TEST-29411\",\n \"createdAt\": \"2025-10-27 00:00:00\",\n \"modifiedAt\": \"2025-10-27 00:00:00\",\n \"modifiedBy\": 1231123,\n \"lastSeenBy\": null,\n \"invoiceType\": \"simplified\",\n \"expenseType\": \"purchase\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\",\n \"inScope\": true\n },\n \"province\": null,\n \"totalGrossAmount\": 143.11,\n \"totalNetAmount\": 119.48,\n \"totalVatAmount\": 23.63,\n \"totalPotentialCashback\": 23.63,\n \"totalApprovedAmount\": 0,\n \"currency\": {\n \"id\": 1,\n \"shortCode\": \"EUR\",\n \"name\": \"Euro\"\n },\n \"vendor\": {\n \"name\": \"Motel One\",\n \"streetName\": \"Immermannstrasse\",\n \"streetNumber\": \"54\",\n \"other\": \"\",\n \"zipCode\": \"40210\",\n \"city\": \"Dusseldorf\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\"\n },\n \"vatNumber\": \"DE123491011\",\n \"taxNumber\": \"\"\n },\n \"importId\": null,\n \"statuses\": {\n \"invoicing\": null,\n \"compliance\": {\n \"id\": 4,\n \"code\": \"NOT_VERIFIED\"\n },\n \"ocr\": {\n \"id\": 201,\n \"code\": \"IN_PROGRESS\"\n },\n \"audit\": {\n \"id\": 30,\n \"code\": \"NOT_VERIFIED\"\n },\n \"refund\": {\n \"id\": 10,\n \"code\": \"EXCLUDED\"\n },\n \"nextStage\": null,\n \"payment\": null,\n \"billing\": null,\n \"dataQuality\": {\n \"id\": 60,\n \"code\": \"NOT_VERIFIED\"\n },\n \"amountVerification\": {\n \"id\": 80,\n \"code\": \"NOT_VERIFIED\"\n },\n \"dateVerification\": {\n \"id\": 1300,\n \"code\": \"NOT_VERIFIED\"\n },\n \"vatFlow\": {\n \"id\": 703,\n \"code\": \"FOREIGN_8TH\"\n },\n \"correction\": {\n \"id\": 800,\n \"code\": \"NOT_VERIFIED\"\n },\n \"restyling\": {\n \"id\": 1001,\n \"code\": \"NOT_REQUIRED\"\n },\n \"duplication\": {\n \"id\": 900,\n \"code\": \"NOT_CHECKED\"\n },\n \"demo\": null,\n \"smartAi\": {\n \"id\": 1500,\n \"code\": \"NOT_PROCESSED\"\n }\n },\n \"nonCompliantReasons\": \"\",\n \"exclusion\": {\n \"reasons\": \"Expired Deadline\",\n \"comment\": null\n },\n \"exchangeRateToEur\": 1,\n \"claim\": null,\n \"additionalComment\": \"\",\n \"optionalFields\": {\n \"DataSource\": null,\n \"TransactionType\": \"Travel expenses\",\n \"ExtractionMethod\": null,\n \"ErpTransactionIdentifier\": null,\n \"TemTransactionIdentifier\": \"019273714123\",\n \"TemTravelReportIdentifier\": null,\n \"ErpTemBookingDate\": null,\n \"ErpGLAccountNumber\": null,\n \"ErpGLAccountName\": null,\n \"ErpGLAccountDebitOrCredit\": null,\n \"LegalEntityCode\": \"LX81623\",\n \"BusinessUnitLevel1\": null,\n \"BusinessUnitLevel2\": null,\n \"BusinessUnitLevel3\": null,\n \"CostCenter\": null,\n \"ProjectNumber\": null,\n \"EmployeeIdentifier\": null,\n \"EmployeeName\": null,\n \"TravelReportPurpose\": null,\n \"ExpenseReceiptDescription\": null,\n \"Comment1\": null,\n \"Comment2\": null,\n \"Comment3\": null,\n \"Comment4\": \"Accommodation, Breakfast\",\n \"Amount1\": null,\n \"Amount2\": null,\n \"Amount3\": null,\n \"InvoiceCorrectionDate\": null,\n \"InvoiceCorrectionBatchId\": null,\n \"VATIdentified\": null\n },\n \"lineItems\": [\n {\n \"netAmount\": 103.51,\n \"vatAmount\": 20.6,\n \"potentialCashback\": 20.6,\n \"grossAmount\": 124.11,\n \"isReverseCharge\": false,\n \"isVatExempt\": false,\n \"userCategory\": \"Accommodation\",\n \"systemCategory\": \"Accommodation\",\n \"vatRate\": 19.9,\n \"deductibilityRate\": 100,\n \"taxKey\": null,\n \"erpGLAccountNumber\": null,\n \"descriptionData\": {\n \"description\": \"\",\n \"language\": \"en\"\n },\n \"poNumber\": null,\n \"poLine\": null,\n \"poDescription\": null\n },\n {\n \"netAmount\": 15.97,\n \"vatAmount\": 3.03,\n \"potentialCashback\": 3.03,\n \"grossAmount\": 19,\n \"isReverseCharge\": false,\n \"isVatExempt\": false,\n \"userCategory\": \"Breakfast\",\n \"systemCategory\": \"Breakfast\",\n \"vatRate\": 19,\n \"deductibilityRate\": 100,\n \"taxKey\": null,\n \"erpGLAccountNumber\": null,\n \"descriptionData\": {\n \"description\": \"\",\n \"language\": \"en\"\n },\n \"poNumber\": null,\n \"poLine\": null,\n \"poDescription\": null\n }\n ],\n \"smartAiResult\": null,\n \"document\": \"https://app.vat4u.local/invoice/audit/79057a5641e2fcb4aae221307f611a41\"\n }\n }\n}"}],"_postman_id":"2dbd7a3a-91c5-4dbd-ad49-66d8c3b2fa91"},{"name":"List expenses","id":"1debc12a-4726-4450-9ecf-0a5d379b7775","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"filter\": [\n {\n \"key\": \"company_name\",\n \"predicate\": \"contains\",\n \"value\": \"123\"\n }\n ],\n \"sort\": {\n \"key\": \"company_name\",\n \"dir\": \"asc\"\n },\n \"page\": 1\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/expenses/filter","description":"Filter and retrieve paginated list of expenses with advanced filtering, sorting, and search capabilities.
\n\n\nThis endpoint allows authenticated users to filter expenses based on various criteria and retrieve paginated results. The user must have appropriate permissions to access expenses for their assigned companies.
\n
Request Body Parameters:
\n{\n \"filter\": [\n {\n \"key\": \"company_name\",\n \"predicate\": \"contains\",\n \"value\": \"1\"\n },\n {\n \"key\": \"total_net_amount\",\n \"predicate\": \"is_greater\",\n \"value\": \"100\"\n },\n {\n \"key\": \"invoice_date\",\n \"predicate\": \"between\",\n \"value\": \"01.01.2024 - 31.12.2024\"\n }\n ],\n \"sort\": {\n \"key\": \"company_name\",\n \"dir\": \"asc\"\n },\n \"page\": 1\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"expenses\": [\n {\n \"id\": 12345,\n \"company_name\": \"Example Company Ltd\",\n \"invoice_number\": \"INV-2024-001\",\n \"total_net_amount\": 150.00,\n \"total_vat_amount\": 30.00,\n \"total_gross_amount\": 180.00,\n \"currency_short_code\": \"EUR\",\n \"invoice_date\": \"2024-01-15\",\n \"vendor_name\": \"Supplier ABC\",\n \"country_name\": \"Germany\",\n \"vat_flow_status_code\": \"processing\"\n }\n ],\n \"hasNextPage\": true\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"1\",\n \"message\": \"Invalid filter parameters or validation error\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"Authentication required\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nThe following fields can be used in the key parameter of filter objects:
company_name (TEXT)
group_contract_name (TEXT)
billed_by_company_name (TEXT)
billed_to_company_name (TEXT)
business_partner_name (TEXT)
coe_name (TEXT)
account_manager_name (TEXT)
delivery_manager_name (TEXT)
processing_manager_name (TEXT)
last_seen_by (TEXT)
user_name (TEXT)
id (INT)
parent_id (INT)
sequence_number (INT)
invoice_number (TEXT)
invoice_type (ENUM)
invoice_date (DATE)
created_date (DATE)
modified_at (DATE)
payment_term_days (INT)
payment_due_date (DATE)
vendor_name (TEXT)
street_name (TEXT)
city (TEXT)
zip_code (TEXT)
vendor_vat_number (TEXT)
vendor_tax_number (TEXT)
total_gross_amount (INT)
total_net_amount (INT)
total_vat_amount (INT)
total_ded_amount (INT)
total_approved_amount (INT)
total_gross_amount_eur (INT)
total_net_amount_eur (INT)
total_vat_amount_eur (INT)
total_ded_amount_eur (INT)
total_gst_amount (INT)
total_hst_amount (INT)
total_pst_amount (INT)
country_name (TEXT)
province_name (TEXT)
country_in_scope (ENUM)
currency_short_code (TEXT)
vat_flow_status_code (ENUM)
refund_status_code (ENUM)
next_stage_status_code (ENUM)
ocr_status_code (ENUM)
audit_status_code (ENUM)
compliance_status_code (ENUM)
correction_status_code (ENUM)
restyling_status_code (ENUM)
data_quality_status_code (ENUM)
amount_verification_status_code (ENUM)
date_verification_status_code (ENUM)
billing_status_code (ENUM)
payment_status_code (ENUM)
demo_status_code (ENUM)
smart_ai_expense_date (DATE)
smart_ai_expense_number (TEXT)
smart_ai_vendor_name (TEXT)
smart_ai_total_net_amount (INT)
smart_ai_total_vat_amount (INT)
smart_ai_total_gross_amount (INT)
smart_ai_batch_tag (TEXT)
smart_ai_country_name (TEXT)
smart_ai_province_name (TEXT)
category_names (TEXT)
claim_id (INT)
tags (OPTIONS_TEXT)
expense_type (TEXT)
import_id (INT)
document_count (INT)
additional_comment (TEXT)
rejection_reason_id (ENUM)
rejection_comment (TEXT)
is - Exact match (supports \"NULL\" for null values, \" or \" for multiple values)
is_not - Not equal to
contains - Contains substring (supports \" or \" for multiple values)
not_contain - Does not contain substring
begins_with - Starts with
ends_with - Ends with
is_empty - Field is null or empty string
is_not_empty - Field is not null and not empty
has_emails - JSON field has email entries (for email fields)
no_emails - JSON field has no email entries (for email fields)
is - Exact match (supports \"NULL\", \" or \" for multiple values)
is_not - Not equal to
is_greater - Greater than
is_lower - Less than
in - In array (expects JSON array of values)
is_empty - Field is null
is_not_empty - Field is not null
is - Exact date match (format: DD.MM.YYYY or DD-MM-YYYY)
is_not - Not on this date
is_year - Year equals
is_not_year - Year not equals
between - Date range (format: \"DD.MM.YYYY - DD.MM.YYYY\")
before - Before date
after - After date
year - Specific year (YYYY)
is_empty - Field is null
is_not_empty - Field is not null
is - Equals (supports arrays and \"NULL\")
is_not - Not equals
is_empty - Field is null
is_not_empty - Field is not null
is - Equals (accepts: yes/y/1/true/green for true, others for false)
is_not - Not equals
is_empty - Field is null
is_not_empty - Field is not null
is - Contains any of the values (expects array)
is_not - Does not contain any of the values
is_empty - Field is null or empty
is_not_empty - Field is not null and not empty
{\n \"key\": \"company_name\",\n \"predicate\": \"contains\",\n \"value\": \"ABC Company\"\n}\n\n{\n \"key\": \"company_name\",\n \"predicate\": \"is\",\n \"value\": \"Company A or Company B\"\n}\n\n{\n \"key\": \"total_net_amount\",\n \"predicate\": \"is_greater\",\n \"value\": \"1000\"\n}\n\n{\n \"key\": \"invoice_date\",\n \"predicate\": \"between\",\n \"value\": \"01.01.2024 - 31.12.2024\"\n}\n\n{\n \"key\": \"vat_flow_status_code\",\n \"predicate\": \"is\",\n \"value\": [\"processing\", \"completed\"]\n}\n\n{\n \"key\": \"vendor_vat_number\",\n \"predicate\": \"is_empty\"\n}\n\nEach expense object contains detailed information about the expense including financial amounts, vendor details, status codes, and metadata.
\nResults are paginated with 20 expenses per page
\nUsers can only access expenses for companies they have permissions for
\nInvalid filter keys or predicates will result in validation errors
\nDate formats must be DD.MM.YYYY or DD-MM-YYYY
\nNumeric values should not contain thousands separators
\nThe system automatically applies user-level permissions to filter results
\nSome fields may require specific table joins and can impact query performance
\nUser authentication is required
\nUser must have appropriate role permissions for expense access
\nValid filter fields and predicates must be used
\nPage parameter must be a positive integer
\nThe endpoint retrieves the details of a specific expense identified by its ID.
\nNo request body is required for this endpoint.
\nThe response will be a JSON object with the following properties:
\n{\n \"id\": 15194675,\n \"parentId\": null,\n \"company\": {\n \"id\": 2, \n \"legalName\": \"VAT4U GmbH\"\n },\n \"date\": \"2025-09-15\",\n \"number\": \"1\",\n \"createdAt\": \"2025-10-27 00:00:00\",\n \"modifiedAt\": \"2025-10-27 00:00:00\",\n \"modifiedBy\": 465,\n \"lastSeenBy\": \"465\",\n \"invoiceType\": \"regular\",\n \"expenseType\": \"purchase\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\",\n \"inScope\": true\n },\n \"province\": null,\n \"totalGrossAmount\": 64.5,\n \"totalNetAmount\": 60.28,\n \"totalVatAmount\": 4.22,\n \"totalPotentialCashback\": 4.22,\n \"totalApprovedAmount\": 0,\n \"currency\": {\n \"id\": 1,\n \"shortCode\": \"EUR\",\n \"name\": \"Euro\"\n },\n \"vendor\": {\n \"name\": \"Taxi Company Berlin GmbH\",\n \"streetName\": \"Mindener Str\",\n \"streetNumber\": \"26\",\n \"other\": \"\",\n \"zipCode\": \"10589\",\n \"city\": \"Berlin\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\"\n },\n \"vatNumber\": \"DE123491011\",\n \"taxNumber\": \"27/555/32204\"\n },\n \"importId\": null,\n \"statuses\": {\n \"invoicing\": null,\n \"compliance\": {\n \"id\": 26,\n \"code\": \"POTENTIALLY_NOT_COMPLIANT\"\n },\n \"ocr\": {\n \"id\": 202,\n \"code\": \"READY\"\n },\n \"audit\": {\n \"id\": 31,\n \"code\": \"VERIFIED_BY_HUMAN\"\n },\n \"refund\": {\n \"id\": 10,\n \"code\": \"EXCLUDED\"\n },\n \"nextStage\": null,\n \"payment\": null,\n \"billing\": null,\n \"dataQuality\": {\n \"id\": 60,\n \"code\": \"NOT_VERIFIED\"\n },\n \"amountVerification\": {\n \"id\": 80,\n \"code\": \"NOT_VERIFIED\"\n },\n \"dateVerification\": {\n \"id\": 1300,\n \"code\": \"NOT_VERIFIED\"\n },\n \"vatFlow\": {\n \"id\": 703,\n \"code\": \"FOREIGN_8TH\"\n },\n \"correction\": {\n \"id\": 800,\n \"code\": \"NOT_VERIFIED\"\n },\n \"restyling\": {\n \"id\": 1001,\n \"code\": \"NOT_REQUIRED\"\n },\n \"duplication\": {\n \"id\": 900,\n \"code\": \"NOT_CHECKED\"\n },\n \"demo\": null,\n \"smartAi\": {\n \"id\": 1503,\n \"code\": \"DATA_RETRIEVED\"\n }\n },\n \"nonCompliantReasons\": \"Not a VAT invoice or receipt;Missing claimant details\",\n \"exclusion\": {\n \"reasons\": \"Expired Deadline\",\n \"comment\": null\n },\n \"exchangeRateToEur\": 1,\n \"claim\": null,\n \"additionalComment\": \"\",\n \"optionalFields\": {\n \"DataSource\": null,\n \"TransactionType\": \"Travel expenses\",\n \"ExtractionMethod\": null,\n \"ErpTransactionIdentifier\": null,\n \"TemTransactionIdentifier\": \"019273714123\",\n \"TemTravelReportIdentifier\": null,\n \"ErpTemBookingDate\": null,\n \"ErpGLAccountNumber\": null,\n \"ErpGLAccountName\": null,\n \"ErpGLAccountDebitOrCredit\": null,\n \"LegalEntityCode\": \"LX81623\",\n \"BusinessUnitLevel1\": null,\n \"BusinessUnitLevel2\": null,\n \"BusinessUnitLevel3\": null,\n \"CostCenter\": null,\n \"ProjectNumber\": null,\n \"EmployeeIdentifier\": null,\n \"EmployeeName\": null,\n \"TravelReportPurpose\": null,\n \"ExpenseReceiptDescription\": null,\n \"Comment1\": null,\n \"Comment2\": null,\n \"Comment3\": null,\n \"Comment4\": \"Accommodation, Breakfast\",\n \"Amount1\": null,\n \"Amount2\": null,\n \"Amount3\": null,\n \"InvoiceCorrectionDate\": null,\n \"InvoiceCorrectionBatchId\": null,\n \"VATIdentified\": null\n },\n \"lineItems\": [\n {\n \"netAmount\": 60.28,\n \"vatAmount\": 4.22,\n \"potentialCashback\": 4.22,\n \"grossAmount\": 64.5,\n \"isReverseCharge\": false,\n \"isVatExempt\": false,\n \"userCategory\": \"\",\n \"systemCategory\": \"Taxi (up to 50 km)\",\n \"vatRate\": 7,\n \"deductibilityRate\": 100,\n \"taxKey\": \"\",\n \"erpGLAccountNumber\": \"\",\n \"descriptionData\": {\n \"description\": \"\",\n \"language\": \"\"\n },\n \"poNumber\": \"\",\n \"poLine\": \"\",\n \"poDescription\": \"\"\n }\n ],\n \"smartAiResult\": {\n \"date\": \"2025-09-15\",\n \"number\": \"1\",\n \"expenseType\": \"receipt\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\",\n \"inScope\": true\n },\n \"province\": null,\n \"totalGrossAmountDocumentCurrency\": 64.5,\n \"totalNetAmountDocumentCurrency\": 0,\n \"totalVatAmountDocumentCurrency\": 0,\n \"totalGrossAmountReportingCurrency\": 0,\n \"totalNetAmountReportingCurrency\": 0,\n \"totalVatAmountReportingCurrency\": 0,\n \"totalGrossAmountReportingCurrencyCalculated\": 0,\n \"totalNetAmountReportingCurrencyCalculated\": 0,\n \"totalVatAmountReportingCurrencyCalculated\": 0,\n \"currency\": {\n \"id\": 1,\n \"shortCode\": \"EUR\",\n \"name\": \"Euro\"\n },\n \"vendor\": {\n \"name\": \"Taxi Company Berlin GmbH\",\n \"streetName\": \"Mindener Str.\",\n \"streetNumber\": \"26\",\n \"zipCode\": \"10589\",\n \"city\": \"Berlin\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\"\n },\n \"vatNumber\": null,\n \"taxNumber\": \"27/555/32204\"\n },\n \"exchangeRateToEur\": null,\n \"mainCategory\": \"Taxi\",\n \"purchaseOrder\": null,\n \"lineItems\": [\n {\n \"netAmount\": 0,\n \"vatAmount\": 0,\n \"grossAmount\": 64.5,\n \"quantity\": null,\n \"unitPrice\": null,\n \"category\": \"Taxi\",\n \"isReverseCharge\": false,\n \"isGoodsOrServices\": \"services\",\n \"vatRate\": 0,\n \"taxKey\": null,\n \"description\": \"Taxi fare\",\n \"purchaseOrder\": null,\n \"productCode\": null\n }\n ]\n },\n \"document\": \"https://app.vat4u.local/invoice/audit/79057a5641e2fcb4aae221307f611a41\"\n}\n\nThe response will contain detailed information about the expense including its ID, company details, dates, amounts, currency, vendor information, statuses, line items, and additional comments.
\nFor users who have SmartAI Advanced enabled, get expense API response now contains SmartAI data quality assesment result.
\nThe qa object contains machine-readable quality assessment results from the extraction pipeline:
Possible flag values:
\nITEMS_GROSS_MISREAD_AS_NET – Item gross amounts are potentially misread as Net - when expense has no clear distinction whether the values reported are Net or Gross.
\nGROSS_NET_VAT_MISMATCH – Gross ≠Net + VAT - Amounts extracted are not consistent with basic sanity check.
\nITEM_AMOUNTS_INCONSISTENT – Per-item amounts are inconsistent
\nITEMS_SUM_MISMATCH – Sum of items does not match extracted expense total amount.
\nTOTALS_MISSING – Required totals are missing - Smart AI could not extract total amounts of the expense
\nVAT_HALLUCINATION – VAT amount may be hallucinated - Either missing from the invoice, or does not seem to be realistic
\nVAT_RATE_INVALID – VAT rate does not match any known rates
\nCURRENCY_MISMATCH – Amounts do not match stated currency
\nEXCHANGE_RATE_MISSING – Multi-currency expense docuemnt detected but no exchange rate
\nLOW_CONFIDENCE – Low extraction confidence
\nMISSING_REQUIRED_FIELDS – Critical fields are missing
\nOCR_QUALITY_POOR – Poor OCR quality
\nID of the expense
\n","type":"text/plain"},"type":"any","value":"","key":"id"}]}},"response":[{"id":"86417652-d4c7-4e19-a90a-c98ceb80cd77","name":"Success","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.vat4u.com/v1/expenses/:id","host":["https://api.vat4u.com"],"path":["v1","expenses",":id"],"variable":[{"key":"id","value":"15194675"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.25.5"},{"key":"Date","value":"Thu, 16 Jan 2025 00:42:17 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Set-Cookie","value":"ci_session=pqr06phsvenpb33kvss314c3tnu59kf2; expires=Thu, 16 Jan 2025 01:12:17 GMT; Max-Age=1800; path=/; domain=app.vat4u.local; secure; HttpOnly; SameSite=Lax"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method"},{"key":"Access-Control-Allow-Methods","value":"GET, POST"},{"key":"X-Proxy-Cache","value":"BYPASS"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": 15194675,\n \"parentId\": null,\n \"company\": {\n \"id\": 2, \n \"legalName\": \"VAT4U GmbH\"\n },\n \"date\": \"2025-09-15\",\n \"number\": \"1\",\n \"createdAt\": \"2025-10-27 00:00:00\",\n \"modifiedAt\": \"2025-10-27 00:00:00\",\n \"modifiedBy\": 465,\n \"lastSeenBy\": \"465\",\n \"invoiceType\": \"regular\",\n \"expenseType\": \"purchase\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\",\n \"inScope\": true\n },\n \"province\": null,\n \"totalGrossAmount\": 64.5,\n \"totalNetAmount\": 60.28,\n \"totalVatAmount\": 4.22,\n \"totalPotentialCashback\": 4.22,\n \"totalApprovedAmount\": 0,\n \"currency\": {\n \"id\": 1,\n \"shortCode\": \"EUR\",\n \"name\": \"Euro\"\n },\n \"vendor\": {\n \"name\": \"Taxi Company Berlin GmbH\",\n \"streetName\": \"Mindener Str\",\n \"streetNumber\": \"26\",\n \"other\": \"\",\n \"zipCode\": \"10589\",\n \"city\": \"Berlin\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\"\n },\n \"vatNumber\": \"DE123491011\",\n \"taxNumber\": \"27/555/32204\"\n },\n \"importId\": null,\n \"statuses\": {\n \"invoicing\": null,\n \"compliance\": {\n \"id\": 26,\n \"code\": \"POTENTIALLY_NOT_COMPLIANT\"\n },\n \"ocr\": {\n \"id\": 202,\n \"code\": \"READY\"\n },\n \"audit\": {\n \"id\": 31,\n \"code\": \"VERIFIED_BY_HUMAN\"\n },\n \"refund\": {\n \"id\": 10,\n \"code\": \"EXCLUDED\"\n },\n \"nextStage\": null,\n \"payment\": null,\n \"billing\": null,\n \"dataQuality\": {\n \"id\": 60,\n \"code\": \"NOT_VERIFIED\"\n },\n \"amountVerification\": {\n \"id\": 80,\n \"code\": \"NOT_VERIFIED\"\n },\n \"dateVerification\": {\n \"id\": 1300,\n \"code\": \"NOT_VERIFIED\"\n },\n \"vatFlow\": {\n \"id\": 703,\n \"code\": \"FOREIGN_8TH\"\n },\n \"correction\": {\n \"id\": 800,\n \"code\": \"NOT_VERIFIED\"\n },\n \"restyling\": {\n \"id\": 1001,\n \"code\": \"NOT_REQUIRED\"\n },\n \"duplication\": {\n \"id\": 900,\n \"code\": \"NOT_CHECKED\"\n },\n \"demo\": null,\n \"smartAi\": {\n \"id\": 1503,\n \"code\": \"DATA_RETRIEVED\"\n }\n },\n \"nonCompliantReasons\": \"Not a VAT invoice or receipt;Missing claimant details\",\n \"exclusion\": {\n \"reasons\": \"Expired Deadline\",\n \"comment\": null\n },\n \"exchangeRateToEur\": 1,\n \"claim\": null,\n \"additionalComment\": \"\",\n \"optionalFields\": {\n \"DataSource\": null,\n \"TransactionType\": \"Travel expenses\",\n \"ExtractionMethod\": null,\n \"ErpTransactionIdentifier\": null,\n \"TemTransactionIdentifier\": \"019273714123\",\n \"TemTravelReportIdentifier\": null,\n \"ErpTemBookingDate\": null,\n \"ErpGLAccountNumber\": null,\n \"ErpGLAccountName\": null,\n \"ErpGLAccountDebitOrCredit\": null,\n \"LegalEntityCode\": \"LX81623\",\n \"BusinessUnitLevel1\": null,\n \"BusinessUnitLevel2\": null,\n \"BusinessUnitLevel3\": null,\n \"CostCenter\": null,\n \"ProjectNumber\": null,\n \"EmployeeIdentifier\": null,\n \"EmployeeName\": null,\n \"TravelReportPurpose\": null,\n \"ExpenseReceiptDescription\": null,\n \"Comment1\": null,\n \"Comment2\": null,\n \"Comment3\": null,\n \"Comment4\": \"Accommodation, Breakfast\",\n \"Amount1\": null,\n \"Amount2\": null,\n \"Amount3\": null,\n \"InvoiceCorrectionDate\": null,\n \"InvoiceCorrectionBatchId\": null,\n \"VATIdentified\": null\n },\n \"lineItems\": [\n {\n \"netAmount\": 60.28,\n \"vatAmount\": 4.22,\n \"potentialCashback\": 4.22,\n \"grossAmount\": 64.5,\n \"isReverseCharge\": false,\n \"isVatExempt\": false,\n \"userCategory\": \"\",\n \"systemCategory\": \"Taxi (up to 50 km)\",\n \"vatRate\": 7,\n \"deductibilityRate\": 100,\n \"taxKey\": \"\",\n \"erpGLAccountNumber\": \"\",\n \"descriptionData\": {\n \"description\": \"\",\n \"language\": \"\"\n },\n \"poNumber\": \"\",\n \"poLine\": \"\",\n \"poDescription\": \"\"\n }\n ],\n \"smartAiResult\": {\n \"date\": \"2025-09-15\",\n \"number\": \"1\",\n \"expenseType\": \"receipt\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\",\n \"inScope\": true\n },\n \"province\": null,\n \"totalGrossAmountDocumentCurrency\": 64.5,\n \"totalNetAmountDocumentCurrency\": 0,\n \"totalVatAmountDocumentCurrency\": 0,\n \"totalGrossAmountReportingCurrency\": 0,\n \"totalNetAmountReportingCurrency\": 0,\n \"totalVatAmountReportingCurrency\": 0,\n \"totalGrossAmountReportingCurrencyCalculated\": 0,\n \"totalNetAmountReportingCurrencyCalculated\": 0,\n \"totalVatAmountReportingCurrencyCalculated\": 0,\n \"currency\": {\n \"id\": 1,\n \"shortCode\": \"EUR\",\n \"name\": \"Euro\"\n },\n \"vendor\": {\n \"name\": \"Taxi Company Berlin GmbH\",\n \"streetName\": \"Mindener Str.\",\n \"streetNumber\": \"26\",\n \"zipCode\": \"10589\",\n \"city\": \"Berlin\",\n \"country\": {\n \"name\": \"Germany\",\n \"shortCode\": \"DE\"\n },\n \"vatNumber\": null,\n \"taxNumber\": \"27/555/32204\"\n },\n \"exchangeRateToEur\": null,\n \"mainCategory\": \"Taxi\",\n \"purchaseOrder\": null,\n \"lineItems\": [\n {\n \"netAmount\": 0,\n \"vatAmount\": 0,\n \"grossAmount\": 64.5,\n \"quantity\": null,\n \"unitPrice\": null,\n \"category\": \"Taxi\",\n \"isReverseCharge\": false,\n \"isGoodsOrServices\": \"services\",\n \"vatRate\": 0,\n \"taxKey\": null,\n \"description\": \"Taxi fare\",\n \"purchaseOrder\": null,\n \"productCode\": null\n }\n ],\n \"qa\": {\n \"status\": \"HUMAN_REVIEW\",\n \"qualityScore\": 0.82,\n \"flags\": [\n \"VAT_HALLUCINATION\"\n ]\n }\n },\n \"document\": \"https://app.vat4u.local/invoice/audit/79057a5641e2fcb4aae221307f611a41\"\n}"}],"_postman_id":"8f5acc08-518b-40d0-a884-acc2e177bf3b"},{"name":"Enrich expense","id":"b8f9e5f5-1fbe-443d-a7c2-8a8cfea1646d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"fields\": [\n {\n \"name\": \"date\",\n \"method\": \"use-when-empty\"\n },\n {\n \"name\": \"number\",\n \"method\": \"use-when-identified\"\n },\n {\n \"name\": \"vendorName\",\n \"method\": \"use-when-empty-or-diff\"\n },\n {\n \"name\": \"streetName\",\n \"method\": \"use-when-empty-or-diff\"\n },\n {\n \"name\": \"streetNumber\",\n \"method\": \"use-when-empty-or-diff\"\n },\n {\n \"name\": \"zipCode\",\n \"method\": \"use-when-empty\"\n },\n {\n \"name\": \"city\",\n \"method\": \"use-when-identified\"\n },\n {\n \"name\": \"vatNumber\",\n \"method\": \"use-when-empty-or-diff\"\n },\n {\n \"name\": \"taxNumber\",\n \"method\": \"use-when-empty\"\n },\n {\n \"name\": \"totaNetAmount\",\n \"method\": \"use-when-empty\"\n },\n {\n \"name\": \"totalVatAmount\",\n \"method\": \"use-when-empty\"\n },\n {\n \"name\": \"currency\",\n \"method\": \"use-when-empty\"\n },\n {\n \"name\": \"country\",\n \"method\": \"use-when-identified\"\n },\n {\n \"name\": \"vendorCountry\",\n \"method\": \"use-when-identified\"\n },\n {\n \"name\": \"province\",\n \"method\": \"use-when-empty\"\n },\n {\n \"name\": \"mainCategory\",\n \"method\": \"use-when-empty-or-diff\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/expenses/:id/enrich","description":"Purpose:
This endpoint enriches a single expense record by updating or supplementing its fields from SmartAI retrieved data based on the provided enrichment methods per field.
URL Structure:
\nRequest Body:
\nContent-Type: application/json
Structure:
\n {\n \"fields\": [\n { \"name\": \"<fieldName>\", \"method\": \"<enrichmentMethod>\" },\n ...\n ]\n }\n\nfields: Array of objects specifying which fields to enrich and the method to use for each.
\nname: Name of the expense field (e.g., date, number, vendorName, etc.).
method: Enrichment strategy. Possible values:
use-when-empty: Enrich only if the original data (user provided data) is empty for the field.
use-when-identified: Enrich if the field value was identified by SmartAI regardless to wheather data was originally provided or not.
use-when-empty-or-diff: Enrich if the field is empty or differs from the originally provided value.
Usage Notes:
\nOnly the specified fields in the fields array will be considered for enrichment.
Ensure the id in the URL matches the expense you wish to enrich.
Special case for expense items:
\nIf you wish to use SmartAI identified items include mainCategory in the list of fields. In this case, SmartAI identified items, including categories and amounts per item will be used.
ID of the expense to be enriched
\n","type":"text/plain"},"type":"any","value":"","key":"id"}]}},"response":[],"_postman_id":"b8f9e5f5-1fbe-443d-a7c2-8a8cfea1646d"},{"name":"Delete expense","id":"0989bd3e-8bf0-4d01-8ae7-be01ac97faf6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"https://api.vat4u.com/v1/expenses/:id","description":"DELETE method with /expenses/{ID} endpoint will delete expense indentified by the ID parameter.
\nA successful call to the endpoint will result in 202 OK status, with an empty response body.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}},"urlObject":{"path":["v1","expenses",":id"],"host":["https://api.vat4u.com"],"query":[],"variable":[{"type":"any","value":"","key":"id"}]}},"response":[{"id":"3a4d50b1-4218-4d13-b08e-c72c5fda5ac9","name":"Successful call to delete single expense with ID 12345","originalRequest":{"method":"DELETE","header":[],"url":"https://api.vat4u.com/v1/expenses/12345"},"status":"Ok","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 12 Jan 2021 16:19:28 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"120"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"ab6c8b5c-129a-4177-b9ea-625382d13cbb"},{"key":"x-amzn-ErrorType","value":"IncompleteSignatureException"},{"key":"x-amz-apigw-id","value":"ZCzSmHRBFiAFUAA="}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"0989bd3e-8bf0-4d01-8ae7-be01ac97faf6"}],"id":"1e728f7e-b299-4445-8d37-b76d35ba090e","_postman_id":"1e728f7e-b299-4445-8d37-b76d35ba090e","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}}},{"name":"Import","item":[{"name":"Initiate Expense Import","id":"ca2e10b1-7c6e-49d2-bd85-614983569954","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n\t\"type\": \"data\",\n\t\"companyId\": \"90272160-4ffd-4eba-9a46-ab9661544259\",\n\t\"categoriesMappingId\": \"af833502-1851-496a-bb34-80da5b463a55\",\n\t\"columnsMappingId\": \"3e034d39-5795-438e-9bf3-9da10b4981e2\",\n\t\"documentsDestination\": null,\n \"dataFileName\": \"example.csv\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/import","description":"Create a new import job.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}},"urlObject":{"path":["v1","import"],"host":["https://api.vat4u.com"],"query":[],"variable":[]}},"response":[{"id":"6fa1b068-e8d3-46ab-aac1-0df26c45e6d5","name":"Initiate data + scans expense import with API as document destination","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n\t\"type\": \"data+scans\",\n\t\"companyId\": \"a61a8fbc-9459-4525-acf8-c133dea96b71\",\n\t\"categoriesMappingId\": \"af833502-1851-496a-bb34-80da5b463a55\",\n\t\"columnsMappingId\": \"3e034d39-5795-438e-9bf3-9da10b4981e2\",\n\t\"documentsDestination\": \"API\",\n \"dataFileName\": \"example.csv\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/import"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": {\n \"importKey\": \"9daef24a-24b9-454f-a818-f401a1b77f5e\",\n \"type\": \"data+scans\",\n \"dataLocation\": {\n \"url\": \"https://example.com?signature\",\n \"expiresIn\": 8400\n },\n \"documentsLocation\": {\n \"url\": \"https://example.com?signature\",\n \"expiresIn\": 8400\n }\n }\n}"},{"id":"7109a4fe-79c7-441b-b59e-8f55524a22ef","name":"Initiate Data only expense import","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n\t\"type\": \"data\",\n\t\"companyId\": \"a61a8fbc-9459-4525-acf8-c133dea96b71\",\n\t\"categoriesMappingId\": \"af833502-1851-496a-bb34-80da5b463a55\",\n\t\"columnsMappingId\": \"3e034d39-5795-438e-9bf3-9da10b4981e2\",\n \"dataFileName\": \"example.csv\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/import"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": {\n \"importKey\": \"9daef24a-24b9-454f-a818-f401a1b77f5e\",\n \"type\": \"data\",\n \"dataLocation\": {\n \"url\": \"https://example.com?signature\",\n \"expiresIn\": 8400\n }\n }\n}"},{"id":"79d8971f-611b-42ef-961c-96953905fee1","name":"Initiate data + scans expense import with external document location","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n\t\"type\": \"data+scans\",\n\t\"companyId\": \"a61a8fbc-9459-4525-acf8-c133dea96b71\",\n\t\"categoriesMappingId\": \"af833502-1851-496a-bb34-80da5b463a55\",\n\t\"columnsMappingId\": \"3e034d39-5795-438e-9bf3-9da10b4981e2\",\n\t\"documentsDestination\": \"EXTERNAL\",\n \"dataFileName\": \"example.csv\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/import"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": {\n \"importKey\": \"9daef24a-24b9-454f-a818-f401a1b77f5e\",\n \"type\": \"data+scans\",\n \"dataLocation\": {\n \"url\": \"https://example.com?signature\",\n \"expiresIn\": 8400\n }\n }\n}"},{"id":"d161265f-fd3d-4b8b-bfef-ad94793a95e1","name":"Initiate data + scans expense import with SFTP as document destination","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n\t\"type\": \"data+scans\",\n\t\"companyId\": \"a61a8fbc-9459-4525-acf8-c133dea96b71\",\n\t\"categoriesMappingId\": \"af833502-1851-496a-bb34-80da5b463a55\",\n\t\"columnsMappingId\": \"3e034d39-5795-438e-9bf3-9da10b4981e2/\",\n\t\"documentsDestination\": \"SFTP\",\n \"dataFileName\": \"example.csv\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/import"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": {\n \"importKey\": \"9daef24a-24b9-454f-a818-f401a1b77f5e\",\n \"type\": \"data+scans\",\n \"dataLocation\": {\n \"url\": \"https://example.com?signature\",\n \"expiresIn\": 8400\n },\n \"documentsLocation\": {\n\t\t \"url\": \"sftp://imports/9daef24a-24b9-454f-a818-f401a1b77f5e\",\n\t\t \"expiresIn\": -1\n }\n }\n}"}],"_postman_id":"ca2e10b1-7c6e-49d2-bd85-614983569954"}],"id":"1e313326-8bec-4c48-80c1-3c2c04c24a69","description":"The main purpose of the Import API module is to provide support for mass data and documents import. POST to /import endpoint allows clients to create an Import Job. That's the start of the import process. Only import job itself doesn't contain any Expense data. Data and/or documents will come later in the import pipeline.
\nWe distinguish multiple scenarios for import:
\nData only (expense data without expense documents)Data + Scans (expense data with scans or images representing expense documents)Each import job request should specify corresponding parameters to have import successfully queued and processed.
\nExpense data (expense lines and items) are always supplied in form of CSV file, containing necessary columns and conforming to Column mapping specified in Import initiation request.
\nYou can download CSV protocol reference file and example CSV from the following links respectively.\nCSV Reference Document v2.19 | CSV Sample v2.19
\nWhen importing data only, first you create an import job and then upload CSV file containing data at signed url parameter returned by /import endpoint under dataLocation property.
This upload is Async in nature. You will always receive 201 Created response if CSV data file is successfully uploaded. Job is queued and will be processed independently from the request timeline.
\nWhen you specify data + scans import type, two options for documents upload are available:
\nDepending on documentsDestination property in create import request, the returned data object will contain the destination at which documents are expected to be found when Job processing starts (after data file is uploaded).
\nGeneral requirements\nRegardless to methods used to supply documents, VAT4U platform will accept documents only in [\"application/pdf\", \"image/jpeg\", \"image/png\"] formats.\nA single document should not exceed the size of 5MB.
When API is specified as the destination, create import function will return temporary URL under documentsLocation.url property where client is supposed to initiate document upload first, and only when documents are uploaded successfully you should proceed with data upload, in the same way as for data only CSV upload. Documents are accepted in form of ZIP archive.\nThe size limit of the ZIP archive is 5GB. Files over 5GB will be rejected if upload to the signed URL is attempted.\nFiles inside ZIP should all comply with general document requirements. Files that do not comply with general document requirements will not be attached to corresponding expenses lines.
ZIP archive must comply with file ZIP format and use a deflate option for Zip compression.
\nEach document should have a name corresponding to the Document reference field inside CSV data file.\nexample CSV line
where 22183-14819-12313.pdf is one of the documents supplied inside ZIP file.
Keep in mind that VAT4U will look only inside a top level directory inside ZIP file. ZIP should not contain Directory hierarchy of any kind.
\n![\"Import](\"https://cdn.vat4u.com/media/import-sftp.svg\")
When SFTP is specified as the destination, response of create import function will contain the SFTP directory at which the client should upload all attachments, 1 by 1, before initiating the upload of the CSV data file.\nThe same CSV file structure applies for both API and SFTP destinations, as file name is used inside Document Reference Field of CSV file. The link between the Expense line inside the CSV file and the corresponding document is created by the document name.\nSFTP access details are to be provided during the integration phase.
\n![\"Import](\"https://cdn.vat4u.com/media/import-external.svg\")
When External URL is specified as the document file location, Import function will look for downloadable attachment under URL provided by the client inside Document Reference Field of CSV data file.\nThis method should be used when a client can provide a publicly accessible endpoint for Document, so the VAT4U system can access (download) documents from external URL backed by a client system.
\nExample CSV file would have the following structure in this scenario:
\n","event":[{"listen":"prerequest","script":{"id":"17532052-87c7-4a82-9f0d-6edd3d9e3a82","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"c25ea413-3c06-4791-bfe1-aad8f3d15c40","type":"text/javascript","exec":[""]}}],"_postman_id":"1e313326-8bec-4c48-80c1-3c2c04c24a69","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}}},{"name":"Company","item":[{"name":"Config","item":[{"name":"List business areas","id":"4709bf72-4ea2-43c4-bb9b-d9a5fb5db9b1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/companies/business_areas","description":"This endpoint retrieves a list of business areas associated with companies.
\nNo request parameters are required for this GET request.
\nThe response will include a JSON object containing the following key:
\nbusiness_areas: An array of business area objects, each containing details relevant to the business area.Ensure that you have the necessary permissions to access this endpoint.
\nThe response may vary based on the user's access level and the data available in the system.
\nCreate a new company in the platform.
\n\n\nThis endpoint allows Expert or Franchisee service providers to create new companies. The authenticated user must have Administrator role in an Expert company or be part of a Franchisee organization.
\n
Request Body Parameters:
\n{\n \"legalName\": \"Company ABC\", \n \"countryCode\": \"DE\", \n \"phoneNumber\": \"+1234567890\", \n \"contactEmail\": \"contact-primary@example.com\",\n \"contactEmail2\": \"contact-alternative@example.com\",\n \"street\": \"Street Name\",\n \"streetNumber\": \"23\",\n \"streetOther\": \"B-12\",\n \"city\": \"Duesseldorf\",\n \"province\": \"NRW\",\n \"zipCode\": \"40210\",\n \"additionalInfo\": \"\",\n \"groupContractCompanyKey\": \"\",\n \"businessAreaKey\": \"b3406b12-3619-4ccf-95fb-eed1dedd1729\",\n \"accountNumber\": \"23422298910\",\n \"canadaTaxReportingType\": \"simplified\",\n \"qstEligible\": true\n}\n\nSuccess Response (HTTP 201 Created):
\n{\n \"status\": \"success\",\n \"data\": {\n \"key\": \"UUID\",\n \"legalName\": \"Company ABC\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Error description\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have permission to create a company for this service provider.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nRequest Body Parameters Description:
\nResponse Fields Description:
\nBusiness Rules and Validation:
\nThe authenticated user must be an Administrator of an Expert company or belong to a Franchisee organization
\nIf groupContractCompanyKey is provided, the user must be an Administrator of that group contract company
The countryCode must be a valid ISO 3166 Alpha 2 country code
The businessAreaKey must reference an existing business area in the system
The serviceProviderKey must reference an existing company from the system that is setup as an Expert of Franchisee.
All email addresses must be in valid email format
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in an Expert or Franchisee company
\nThe business area specified must exist in the system
\nRetrieve list of companies from the platform.
\n\n\nThis endpoint has pagination. Pay attention to the page URL query parameter. If you omit this parameter API will return all companies from your profile. Hint: This is useful if you would like to retrieve all the records in a single API call.
\n
Query parameters:
\npage: Number (optional) - Page to be returned when using pagination. If ommited system will return first 10.000 records.\nmodifiedAfter: Date (optional) use to filter entities that have modifiedAt date after the specified date (format YYYY-MM-DD).\n\n{\n \"status\": \"success\",\n \"data\": [{List of companies}],\n \"pagination\": {\n \"totalRecords\": {Total number of companies},\n \"currentPage\": {Returned page},\n \"perPage\": {Number of companies per page},\n \"totalPages\": {Total number of pages in the API}\n }\n}\n\nCompany object:
\n{\n \"id\": 123456,\n \"key\": \"UUID\",\n \"legalName\": \"Test Company ABC\",\n \"contactPhone\": \"+490000000000\",\n \"contactEmail\": \"test@vat4u.com\",\n \"contactEmail_2\": \"test-2@vat4u.com\",\n \"address\": {\n \"street\": \"Kreuzstr\",\n \"houseNumber\": \"34\",\n \"other\": \"\",\n \"city\": \"Duesseldorf\",\n \"province\": \"NRW\",\n \"zipCode\": \"40210\",\n \"additionalInfo\": \"\",\n \"es\": { \n \"roadType\": null,\n \"province\": null,\n \"houseNumberType\": null\n },\n \"pl\": {\n \"numberRegion\": \"\",\n \"county\": \"\",\n \"community\": \"\",\n \"postOffice\": \"\",\n \"taxOffice_code\": \"\"\n }\n },\n \"invoicing\": {\n \"purchasingInfo\": null,\n \"supplierNumber\": \"\",\n \"invoicingEmail\": \"\",\n \"invoicingEmailCc\": null,\n \"paymentReminderEmail\": \"\",\n \"invoicingContact\": {\n \"title\": \"\",\n \"first_name\": \"\",\n \"last_name\": \"\"\n }\n },\n \"countryOfEstablishment\": {\n \"id\": 654321,\n \"code\": \"DE\",\n \"name\": \"Germany\"\n },\n \"banks\": [],\n \"vatInformation\": {\n \"taxOffice\": null,\n \"taxOfficeAddress\": \"\",\n \"taxNumber\": \"\",\n \"isTaxGroupMember\": false,\n \"taxGroupNumber\": null,\n \"taxGroupName\": null,\n \"taxCertificates\": [\n {\n \"id\": 12345,\n \"createdBy\": 4455,\n \"validFrom\": \"2022-02-01 00:00:00\",\n \"validTo\": \"2023-02-18 23:59:59\",\n \"createdAt\": \"2024-02-01 08:57:22\"\n }\n ],\n \"referenceNumbers\": [\n {\n \"id\": 1303,\n \"countryId\": 52,\n \"refNumber\": \"0123456\"\n },\n {\n \"id\": 1304,\n \"countryId\": 50,\n \"refNumber\": \"1234123\"\n }\n ],\n \"vatRegistrations\": [\n {\n \"id\": 982,\n \"countryId\": 48,\n \"refNumber\": \"293481723\",\n \"validFrom\": \"2024-02-01 00:00:00\",\n \"validTo\": \"2024-02-23 23:59:59\",\n \"excludeFromImport\": false\n }\n ]\n },\n \"representatives\": [],\n \"businessActivity\": {\n \"codes\": [],\n \"description\": null,\n \"businessArea\": {\n \"key\": \"4d4613bf-448d-416e-800a-d0dbfa3be431\",\n \"name\": \"Regular companies\"\n }\n },\n \"customFields\": [],\n \"documents\": [],\n \"groupContractMainCompanyId\": 123456,\n \"isInactive\": false,\n \"isDemo\": false,\n \"accountNumber\": null,\n \"accountManagement\": {\n \"accountManagerId\": 0,\n \"processManagerId\": 0,\n \"deliveryManagerId\": 0,\n \"accountManagerComment\": null,\n \"processManagerComment\": null,\n \"deliveryManagerComment\": null\n },\n \"modified_at\": \"2024-03-04 13:10:23\"\n }\n\nSingle company object fields description
\nPhysical address details
\nPhysical address details
\nBilling and invoicing details - Used together with VAT4U Invoicing module
\nCountry of establishment
\nCountry of establishment
\nBank details object of the 'banks' array
\nDetails of the 'vatInformation' object
This object is representing details about the legal entity information related to VAT Information settings.
Details of the 'representatives' array objects
\nRepresents list of entites which can be introduced as Claim Representatives during the claim creation.
\nDetails of the 'businessActivity' object
\nDetails of the 'accountManagement' object
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}},"urlObject":{"path":["v1","companies"],"host":["https://api.vat4u.com"],"query":[{"key":"page","value":"0"},{"key":"modifiedAfter","value":"2023-03-12"}],"variable":[]}},"response":[{"id":"319cc77f-eaba-414e-be1c-aa5a0785780c","name":"Successful response","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.vat4u.com/v1/companies?page=0","host":["https://api.vat4u.com"],"path":["v1","companies"],"query":[{"key":"page","value":"0"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": [],\n \"pagination\": {\n \"totalRecords\": 83,\n \"currentPage\": 0,\n \"perPage\": 25,\n \"totalPages\": 4\n }\n}"}],"_postman_id":"773bf620-76b0-44d2-b6a9-c35fbd9ec920"},{"name":"Single company","id":"7977841c-5a19-423b-927b-a0deb46c82ee","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.vat4u.com/v1/companies/:companyKey","description":"Retrieve a single company by KEY.
\nPath parameters:
\nInclude company \"key\" from the list of companies to retrieve a single company data.\n\nResponse:
\n{\n \"status\": \"success\",\n \"data\": [{Company object}],\n}\n\nCompany object:
\n{\n \"id\": 123456,\n \"key\": \"UUID\",\n \"legalName\": \"Test Company ABC\",\n \"contactPhone\": \"+490000000000\",\n \"contactEmail\": \"test@vat4u.com\",\n \"contactEmail_2\": \"test-2@vat4u.com\",\n \"address\": {\n \"street\": \"Kreuzstr\",\n \"houseNumber\": \"34\",\n \"other\": \"\",\n \"city\": \"Duesseldorf\",\n \"province\": \"NRW\",\n \"zipCode\": \"40210\",\n \"additionalInfo\": \"\",\n \"es\": { \n \"roadType\": null,\n \"province\": null,\n \"houseNumberType\": null\n },\n \"pl\": {\n \"numberRegion\": \"\",\n \"county\": \"\",\n \"community\": \"\",\n \"postOffice\": \"\",\n \"taxOffice_code\": \"\"\n }\n },\n \"invoicing\": {\n \"purchasingInfo\": null,\n \"supplierNumber\": \"\",\n \"invoicingEmail\": \"\",\n \"invoicingEmailCc\": null,\n \"paymentReminderEmail\": \"\",\n \"invoicingContact\": {\n \"title\": \"\",\n \"first_name\": \"\",\n \"last_name\": \"\"\n }\n },\n \"countryOfEstablishment\": {\n \"id\": 654321,\n \"code\": \"DE\",\n \"name\": \"Germany\"\n },\n \"banks\": [],\n \"vatInformation\": {\n \"taxOffice\": null,\n \"taxOfficeAddress\": \"\",\n \"taxNumber\": \"\",\n \"isTaxGroupMember\": false,\n \"taxGroupNumber\": null,\n \"taxGroupName\": null,\n \"taxCertificates\": [\n {\n \"id\": 12345,\n \"createdBy\": 4455,\n \"validFrom\": \"2022-02-01 00:00:00\",\n \"validTo\": \"2023-02-18 23:59:59\",\n \"createdAt\": \"2024-02-01 08:57:22\"\n }\n ],\n \"referenceNumbers\": [\n {\n \"id\": 1303,\n \"countryId\": 52,\n \"refNumber\": \"0123456\"\n },\n {\n \"id\": 1304,\n \"countryId\": 50,\n \"refNumber\": \"1234123\"\n }\n ],\n \"vatRegistrations\": [\n {\n \"id\": 982,\n \"countryId\": 48,\n \"refNumber\": \"293481723\",\n \"validFrom\": \"2024-02-01 00:00:00\",\n \"validTo\": \"2024-02-23 23:59:59\",\n \"excludeFromImport\": false\n }\n ]\n },\n \"representatives\": [],\n \"businessActivity\": {\n \"codes\": [],\n \"description\": null,\n \"businessArea\": {\n \"key\": \"4d4613bf-448d-416e-800a-d0dbfa3be431\",\n \"name\": \"Regular companies\"\n }\n },\n \"customFields\": [],\n \"documents\": [],\n \"groupContractMainCompanyId\": 123456,\n \"isInactive\": false,\n \"isDemo\": false,\n \"accountNumber\": null,\n \"accountManagement\": {\n \"accountManagerId\": 0,\n \"processManagerId\": 0,\n \"deliveryManagerId\": 0,\n \"accountManagerComment\": null,\n \"processManagerComment\": null,\n \"deliveryManagerComment\": null\n },\n \"modified_at\": \"2024-03-04 13:10:23\"\n }\n\nSingle company object fields description
\nPhysical address details
\nPhysical address details
\nBilling and invoicing details - Used together with VAT4U Invoicing module
\nCountry of establishment
\nCountry of establishment
\nBank details object of the 'banks' array
\nDetails of the 'vatInformation' object
This object is representing details about the legal entity information related to VAT Information settings.
Details of the 'representatives' array objects
\nRepresents list of entites which can be introduced as Claim Representatives during the claim creation.
\nDetails of the 'businessActivity' object
\nDetails of the 'accountManagement' object
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}},"urlObject":{"path":["v1","companies",":companyKey"],"host":["https://api.vat4u.com"],"query":[],"variable":[{"type":"any","value":"","key":"companyKey"}]}},"response":[{"id":"fee5f747-872b-40c8-bda1-9e1c1d3c7390","name":"Successful response","originalRequest":{"method":"GET","header":[],"url":"https://api.vat4u.com/v1/companies/4cea7660-5d81-4e93-a7be-16aad180434f"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method"},{"key":"Access-Control-Allow-Methods","value":"GET, POST"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Content-Encoding","value":"gzip"},{"key":"Content-Length","value":"651"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Tue, 23 Apr 2024 12:02:10 GMT"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Pragma","value":"no-cache"},{"key":"Server","value":"Apache/2.4.41 (Ubuntu)"},{"key":"Set-Cookie","value":"ci_session=q01motteb94t13fin7u7g3ldecgv5cof; expires=Tue, 23-Apr-2024 12:32:10 GMT; Max-Age=1800; path=/; domain=.app.vat4u.local; secure; HttpOnly; SameSite=Lax"},{"key":"Vary","value":"Accept-Encoding"},{"key":"X-Powered-By","value":"PHP/7.4.33"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": {\n \"id\": 14693,\n \"key\": \"4cea7660-5d81-4e93-a7be-16aad180434f\",\n \"legalName\": \"Demo - 14693\",\n \"contactPhone\": null,\n \"contactEmail\": \"\",\n \"contactEmail_2\": \"\",\n \"address\": {\n \"street\": \"\",\n \"houseNumber\": \"\",\n \"other\": \"\",\n \"city\": \"\",\n \"province\": \"\",\n \"zipCode\": \"\",\n \"additionalInfo\": \"\",\n \"es\": {\n \"roadType\": null,\n \"province\": null,\n \"houseNumberType\": null\n },\n \"pl\": {\n \"numberRegion\": \"\",\n \"county\": \"\",\n \"community\": \"\",\n \"postOffice\": \"\",\n \"taxOffice_code\": \"\"\n }\n },\n \"invoicing\": {\n \"purchasingInfo\": null,\n \"supplierNumber\": \"\",\n \"invoicingEmail\": \"\",\n \"invoicingEmailCc\": null,\n \"paymentReminderEmail\": \"\",\n \"invoicingContact\": {\n \"title\": \"\",\n \"first_name\": \"\",\n \"last_name\": \"\"\n }\n },\n \"countryOfEstablishment\": {\n \"id\": 12,\n \"code\": \"IT\",\n \"name\": \"Italy\"\n },\n \"banks\": [],\n \"vatInformation\": {\n \"taxOffice\": null,\n \"taxOfficeAddress\": \"\",\n \"taxNumber\": \"\",\n \"isTaxGroupMember\": false,\n \"taxGroupNumber\": null,\n \"taxGroupName\": null,\n \"taxCertificates\": [],\n \"referenceNumbers\": [],\n \"vatRegistrations\": []\n },\n \"representatives\": [],\n \"businessActivity\": {\n \"codes\": [],\n \"description\": null,\n \"businessArea\": {\n \"key\": \"4d4613bf-448d-416e-800a-d0dbfa3be431\",\n \"name\": \"Regular companies\"\n }\n },\n \"customFields\": [],\n \"documents\": [],\n \"groupContractMainCompanyId\": 14693,\n \"isInactive\": false,\n \"isDemo\": false,\n \"accountNumber\": null,\n \"accountManagement\": {\n \"accountManagerId\": null,\n \"processManagerId\": null,\n \"deliveryManagerId\": null,\n \"accountManagerComment\": null,\n \"processManagerComment\": null,\n \"deliveryManagerComment\": null\n },\n \"modifiedAt\": \"2024-03-04 12:58:05\"\n }\n}"}],"_postman_id":"7977841c-5a19-423b-927b-a0deb46c82ee"},{"name":"Update VAT information","id":"738024b4-ed0c-449c-83a8-c0343b850595","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[],"body":{"mode":"raw","raw":"{\n \"vatNumber\": \"DE123456789\",\n \"localTaxOfficeName\": \"\",\n \"localTaxOfficeAddress\": \"\",\n \"taxNumber\": \"\",\n \"iossNumber\": \"\",\n \"taxGroupMember\": true,\n \"taxGroupNumber\": \"\",\n \"taxGroupName\": \"\",\n \"plTaxOfficeCode\": \"\",\n \"deState\": \"\",\n \"gstin\": \"\",\n \"pan\": \"\",\n \"lut\": \"\",\n \"stateCode\": \"\",\n \"isSez\": false\n}","options":{"raw":{"language":"json"}}},"url":"https://api.vat4u.com/v1/companies/:key/vat_info","description":"Update VAT information for a company.
\n\n\nThis endpoint allows updating VAT-related information for a specific company. VAT information includes tax numbers, office details, group memberships, and country-specific tax data. The authenticated user must have Administrator role in the specified company. All parameters are optional - only provided fields will be updated.
\n
URL Path Parameter:
\n{key} - Company UUID key\n\nRequest Body Parameters:
\n{\n \"vatNumber\": \"\",\n \"localTaxOfficeName\": \"\",\n \"localTaxOfficeAddress\": \"\",\n \"taxNumber\": \"\",\n \"iossNumber\": \"\",\n \"taxGroupMember\": true,\n \"taxGroupNumber\": \"\",\n \"taxGroupName\": \"\",\n \"plTaxOfficeCode\": \"\",\n \"deState\": \"Bayern\",\n \"gstin\": \"\",\n \"pan\": \"\",\n \"lut\": \"\",\n \"stateCode\": \"\",\n \"isSez\": false\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"VAT information updated successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Invalid request fields: field_name1, field_name2\"\n}\n\n{\n \"status\": \"error\",\n \"code\": \"UNKNOWN\",\n \"message\": \"Make sure FASTNR is in correct format. (2 digit TAX office number + 7 digit TAX number, e.g. 22134567).\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"UNKNOWN\",\n \"message\": \"Something went wrong while processing your request. Please try again.\"\n}\n\nRequest Body Parameters Description:
\nURL Parameters Description:
\nCountry-Specific Fields:
\nGermany (DE):
\ndeState: Must be one of the valid German states:
Poland (PL):
\nplTaxOfficeCode: Tax office code for Polish companiesIndia (IN):
\ngstin: Goods and Services Tax Identification Number
pan: Permanent Account Number
lut: Letter of Undertaking
stateCode: Indian state code
isSez: Special Economic Zone membership status
Austria (AT):
\ntaxNumber: Must be in format NNNNNNNN (9 digits: 2-digit tax office number + 7-digit tax number, e.g., 22134567)Business Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\nOnly whitelisted fields are accepted; invalid fields will result in an error
\nAll parameters are optional - only provided fields will be updated
\nvatNumber and taxNumber are automatically converted to uppercase
All string values are trimmed of whitespace
\nSpecial validation applies for Austrian tax numbers (must be 9 digits)
\nCountry-specific fields are validated based on company's country of establishment
\nData Processing:
\nCase Conversion: VAT number and tax number are converted to uppercase
\nTrimming: All string values are trimmed of leading/trailing whitespace
\nPartial Updates: Only fields provided in request are updated
\nField Validation: Invalid field names are rejected with detailed error message
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nCompany must exist and be accessible to the user
\nField names must be from the approved whitelist
\nCountry-specific fields should match company's country of establishment
\nUse Cases:
\nUpdating VAT registration numbers after registration
\nSetting tax office information for compliance
\nConfiguring tax group memberships
\nManaging IOSS numbers for e-commerce businesses
\nUpdating country-specific tax identifiers
\nMaintaining accurate tax compliance data
\nValidation Examples:
\nValid German State:
\n{\n \"deState\": \"Bayern\"\n}\n\nValid Austrian Tax Number:
\n{\n \"taxNumber\": \"123456789\"\n}\n\nTax Group Configuration:
\n{\n \"taxGroupMember\": true,\n \"taxGroupNumber\": \"TG123456\",\n \"taxGroupName\": \"ABC Tax Group\"\n}\n\nIndian Company Fields:
\n{\n \"gstin\": \"27AAPFU0939F1ZV\",\n \"pan\": \"AAPFU0939F\",\n \"isSez\": true\n}\n\nUpdate invoicing details for a company.
\n\n\nThis endpoint allows updating invoicing configuration and settings for a company. The authenticated user must have Administrator role in the specified company and have invoicing module available. This is used together with the VAT4U Invoicing module.
\n
URL Path Parameter:
\n{key} - Company UUID key\n\nRequest Body Parameters:
\n{\n \"invoiceFormat\": \"INV-{S}\",\n \"creditNoteFormat\": \"CRN-{S}\",\n \"orderFormat\": \"ORD-{S}\",\n \"templatePrefix\": \"\",\n \"accountingEmail\": \"accounting@company.com\",\n \"financeBccEmail\": \"finance@company.com\",\n \"financeReminderBccEmail\": \"reminder@company.co,\",\n \"enableEInvoicing\": true,\n \"contactPersonFullName\": \"John Doe\",\n \"contactPersonPhoneNumber\": \"+123 000125555\",\n \"contactPersonEmail\": \"contact@company.com\",\n \"billingReplyEmail\": \"billing@company.com\",\n \"invoiceNote\": \"Contact support for more details\"\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Invoicing details updated successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Error description\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nRequest Body Parameters Description:
\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\nThe user must have invoicing module available in their account
\nAll email fields must be in valid email format when provided
\nFormat fields (invoiceFormat, creditNoteFormat, orderFormat) must include the {S} placeholder if provided
All parameters are optional - only provided fields will be updated
\nThe company specified by the key parameter must exist
Prerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nUser must have invoicing module access
\nCompany must exist and be accessible to the user
\nAdd bank account details to a company.
\n\n\nThis endpoint allows adding new bank account details to a specific company. The authenticated user must have Administrator role in the specified company. Bank account information can include optional supporting documentation uploaded as base64 encoded files.
\n
URL Path Parameter:
\n{key} - Company UUID key\n\nRequest Body Parameters:
\n{\n \"bankAccountName\": \"Bank account name\",\n \"currencyCode\": \"EUR\",\n \"countryCode\": \"FR\",\n \"accountHolderName\": \"Max Maswete\",\n \"bankAddress\": \"StreetName 22\",\n \"iban\": \"09876545678\",\n \"accountNumber\": \"98765456789\",\n \"bic\": \"DEFG124132\",\n \"accountHolderAddress\": \"Street 232\",\n \"bankName\": \"World Bank\",\n \"isDefault\": true,\n \"allowedForClaims\": true,\n \"fileName\": \"Bank.pdf\",\n \"fileContent\": \"<base64_string>\"\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Bank details created successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Error description\"\n}\n\n{\n \"status\": \"error\",\n \"code\": \"File already exists\",\n \"message\": \"File with this name already exists in the system. Please rename the file to proceed.\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nRequest Body Parameters Description:
\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\ncurrencyCode must be a valid 3-letter ISO currency code existing in the system
countryCode must be a valid 2-letter ISO country code existing in the system
accountHolderName accepts only Latin alphabet letters when provided
IBAN and BIC values are automatically converted to uppercase
\nIf isDefault is set to true, all other bank accounts for this company will have their default status removed
File upload is optional but if provided, both fileName and fileContent must be specified
Uploaded files are stored with a unique naming convention: BANK_DETAILS_{recordId}.{extension}
File names must not conflict with existing files in the company's directory
\nThe system creates the company's document directory if it doesn't exist
\nFile Upload Details:
\nFiles are stored in the company-specific directory on the server
\nFile naming format: BANK_DETAILS_{bankRecordId}.{originalExtension}
File size is automatically calculated and stored
\nSupported file formats: Any format with proper extension in filename
\nFiles are decoded from base64 before storage
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nCompany must exist and be accessible to the user
\nValid currency and country codes must be used
\nUse Cases:
\nAdding primary bank account for company payments
\nSetting up multiple currency accounts for international operations
\nConfiguring bank accounts specifically for VAT claim refunds
\nUploading supporting bank documentation for compliance
\nUpdate bank account details for a company.
\n\n\nThis endpoint allows updating an existing bank account for a specific company. The authenticated user must have Administrator role in the specified company. Bank account information can include optional supporting documentation uploaded as base64 encoded files. All parameters are optional - only provided fields will be updated.
\n
URL Path Parameters:
\n{key} - Company UUID key\n{id} - Bank account ID\n\nRequest Body Parameters:
\n{\n \"bankAccountName\": \"Bank account name\",\n \"currencyCode\": \"EUR\",\n \"countryCode\": \"FR\",\n \"accountHolderName\": \"Max Maswete\",\n \"bankAddress\": \"StreetName 22\",\n \"iban\": \"09876545678\",\n \"accountNumber\": \"98765456789\",\n \"bic\": \"DEFG124132\",\n \"accountHolderAddress\": \"Street 232\",\n \"bankName\": \"World Bank\",\n \"isDefault\": true,\n \"allowedForClaims\": true,\n \"fileName\": \"Bank.pdf\",\n \"fileContent\": \"<base64_string>\"\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Bank details updated successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Bank details with id {id} not found for this company\"\n}\n\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Invalid bank details data\"\n}\n\n{\n \"status\": \"error\",\n \"code\": \"File already exists\",\n \"message\": \"File with this name already exists in the system. Please rename the file to proceed.\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nRequest Body Parameters Description:
\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\nThe bank account with the specified id must exist and belong to the company
Only fields provided in the request will be updated; missing fields retain their current values
\nField names must match existing bank detail properties (invalid fields are rejected)
\ncurrencyCode must be a valid 3-letter ISO currency code existing in the system (if provided)
countryCode must be a valid 2-letter ISO country code existing in the system (if provided)
accountHolderName accepts only Latin alphabet letters when provided
IBAN and BIC values are automatically converted to uppercase
\nIf isDefault is set to true, all other bank accounts for this company will have their default status removed
Update Behavior:
\nPartial Updates: Only fields provided in the request will be updated
\nField Retention: Fields not included in the request will keep their existing values
\nMerge Logic: Current bank details are merged with provided updates
\nFile Replacement: Uploading a new file completely replaces the existing file
\nDefault Management: Setting a new default account removes default status from others
\nFile Upload Details:
\nFiles are stored in the company-specific directory on the server
\nFile naming format: BANK_DETAILS_{bankId}.{originalExtension}
File size is automatically calculated and stored
\nSupported file formats: Any format with proper extension in filename
\nFiles are decoded from base64 before storage
\nFile names must not conflict with existing files in the company's directory
\nField Validation:
\nRequest fields are validated against existing bank detail structure
\nUnknown or invalid field names result in \"Invalid bank details data\" error
\nCountry and currency codes are validated against system databases
\nFile upload fields are processed only if both filename and content are provided
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nBank account with specified ID must exist and belong to the company
\nValid currency and country codes must be used (if provided)
\nUse Cases:
\nUpdating bank account information due to changes
\nModifying account holder details
\nChanging default account designation
\nUpdating currency or country information
\nReplacing bank documentation
\nAdjusting claim usage permissions
\nExample Update Scenarios:
\nUpdate Account Name Only:
\n{\n \"bankAccountName\": \"Primary EUR Account\"\n}\n\nChange Default Status:
\n{\n \"isDefault\": true\n}\n\nUpdate File Only:
\n{\n \"fileName\": \"Updated_Bank_Statement.pdf\",\n \"fileContent\": \"base64_encoded_content_here\"\n}\n\nUpdate Multiple Fields:
\n{\n \"bankName\": \"New Bank Name\",\n \"bankAddress\": \"New Address 123\",\n \"allowedForClaims\": false\n}\n\nRetrieve bank details for a company.
\n\n\nThis endpoint allows retrieving all bank account details associated with a specific company. The authenticated user must have Administrator role in the specified company to access this information.
\n
URL Path Parameter:
\n{key} - Company UUID key\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"banks\": [\n {\n \"id\": 123,\n \"bankName\": \"Deutsche Bank AG\",\n \"bankAddress\": \"Taunusanlage 12, 60325 Frankfurt am Main, Germany\",\n \"iban\": \"DE89370400440532013000\",\n \"accountNumber\": \"532013000\",\n \"bic\": \"DEUTDEFF\",\n \"accountHolderName\": \"Company ABC GmbH\",\n \"accountHolderAddress\": \"Kreuzstr 34, 40210 Duesseldorf, Germany\",\n \"bankAccountName\": \"Primary Business Account\",\n \"isDefault\": 1,\n \"allowedForClaims\": 1,\n \"currency\": \"Euro\",\n \"currencyCode\": \"EUR\",\n \"country\": \"Germany\",\n \"countryCode\": \"DE\",\n \"fileName\": \"BANK_DETAILS_123.pdf\",\n \"fileSize\": 245760,\n \"createdAt\": \"2024-01-15 10:30:00\",\n \"createdBy\": 456\n }\n ]\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Error description\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nURL Parameters Description:
\nResponse Fields Description:
\nBank Account Object Fields:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\nOnly bank accounts belonging to the specified company are returned
\nInternal system fields (companyId, countryId, currencyId) are excluded from the response
\nCurrency and country information is expanded to include both full names and short codes
\nIf no bank accounts exist for the company, an empty array is returned
\nFile information (fileName, fileSize) is included only if a document was uploaded for the bank account
\nWhen the bank details are modified the old details are deleted, but kept in the system for audit purposes
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nCompany must exist and be accessible to the user
\nUse Cases:
\nRetrieving bank account information for payment processing
\nDisplaying available bank accounts for VAT claim refunds
\nAuditing company financial account setup
\nIntegrating with external accounting systems
\nDelete bank account details for a company.
\n\n\nThis endpoint allows removing an existing bank account from a specific company. This action permanently removes the bank account information and any associated files from the system. The authenticated user must have Administrator role in the specified company.
\n
URL Path Parameters:
\n{key} - Company UUID key\n{id} - Bank account ID\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Bank details deleted successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Bank details with id {id} not found for this company\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\nThe bank account with the specified id must exist and belong to the company
The bank details entry must be associated with the specified company
\nThe deletion is permanent and cannot be undone through the API
\nAssociated bank statement files are permanently removed from server storage
\nIf the deleted account was the default account, no automatic reassignment occurs
\nAuthorization Requirements:
\nTarget Company: Administrator role required
\nThe user must have administrative access to the company that owns the bank account
\nDouble validation ensures user has proper permissions for both the company and the specific bank account
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nBank account with specified ID must exist
\nBank account must belong to the specified company
\nUse Cases:
\nRemoving closed or invalid bank accounts
\nCleaning up outdated banking information
\nDeleting duplicate bank account entries
\nCompliance with data retention policies
\nRemoving accounts no longer used for business operations
\nImportant Notes:
\nPermanent Action: This operation cannot be undone through the API
\nFile Removal: Associated bank statement/document files are permanently deleted from server storage
\nDefault Account Impact: If a default account is deleted, the company may not have a default bank account until another is designated
\nClaims Impact: Removing accounts marked for claims may affect VAT refund processing capabilities
\nAudit Trail: The deletion action may be logged for audit and compliance purposes
\nSecurity Considerations:
\nOnly users with Administrator role in the company can delete bank accounts
\nThe system validates that the bank account belongs to the specified company
\nCross-company bank account deletion is not permitted
\nDouble permission validation ensures proper authorization
\nRelated Operations:
\nAfter deleting a bank account, you may want to:
\nList remaining bank accounts using the List Bank Details endpoint
\nAdd a new bank account if replacement is needed
\nDesignate a new default account if the deleted account was default
\nReview VAT claim settings if the account was used for claims
\nError Scenarios:
\nBank Account Not Found: When the ID doesn't exist or doesn't belong to the company
\nInsufficient Permissions: When user lacks Administrator role
\nCompany Not Found: When the company UUID is invalid
\nSystem Errors: When database or file system issues occur
\nFinancial Impact Considerations:
\nEnsure all pending transactions are completed before deletion
\nVerify that no active VAT claims are using this account for refunds
\nConsider the impact on financial reporting and reconciliation
\nMaintain proper records for accounting and audit purposes
\nBest Practices:
\nVerify the correct bank account ID before deletion
\nEnsure proper backup of banking information if required by regulations
\nConsider deactivating accounts before permanent deletion
\nCoordinate with finance teams before removing active accounts
\nDocument the reason for bank account removal for audit trails
\nAdd a document to a company.
\n\n\nThis endpoint allows adding documents to a company's document collection. Documents can be uploaded as files (base64 encoded) or stored as URL links. The authenticated user must have Administrator role in the specified company.
\n
URL Path Parameter:
\n{key} - Company UUID key\n\nRequest Body Parameters:
\n{\n \"type\": \"Identity document legal representative\",\n \"name\": \"Document\",\n \"url\": \"\",\n \"fileName\": \"doc.pdf\",\n \"fileContent\": \"<base64_string>\"\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Document created successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Error description\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"error\",\n \"message\": \"Could not store key. Please contact support if problem persists.\"\n}\n\nRequest Body Parameters Description:
\nURL Parameters Description:
\nDocument Upload Modes:
\nFile Upload Mode:
\nProvide both fileName and fileContent
Leave name and url empty
The file will be stored on the server and assigned a unique identifier
\nURL Link Mode:
\nProvide both name and url
Leave fileName and fileContent empty
The document will be stored as a reference to an external URL
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\nEither file upload fields (fileName + fileContent) OR URL fields (name + url) must be provided, but not both
The type field must be one of the predefined valid values
For file uploads, fileContent must be valid base64 encoded data
For URL links, url must be a valid URL format
If document type is Contract, the company's contract flag will be automatically set to true
File extensions are preserved when uploading files
\nEach document gets a unique system-generated identifier
\nValid Document Types:
\nContract - Legal contracts (automatically sets company contract flag)
Commercial Register - Commercial registration documents
Identity document legal representative - ID documents for company representatives
Billing instructions or information - Billing and payment related documents
Other - Any other type of company document
Prerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nCompany must exist and be accessible to the user
\nFor file uploads: sufficient server storage space
\nFor URL links: accessible external URL
\nDelete a company document.
\n\n\nThis endpoint allows removing an existing document from a company's document collection. This action permanently removes the document and its associated files from the system. The authenticated user must have Administrator role in the target company. If the deleted document is a contract and no other contracts remain, the company's contract flag will be automatically set to false.
\n
URL Path Parameters:
\n{key} - Company UUID key\n{documentId} - Document ID (must be numeric)\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Document deleted successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Document id is not valid\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the target company
\nThe documentId must be a valid numeric value (integer)
The document must exist and belong to the specified company
\nThe deletion is permanent and cannot be undone through the API
\nAssociated document files are permanently removed from server storage
\nContract Logic: If the deleted document is of type \"Contract\" and no other contracts remain in the company, the company's contract flag is automatically set to false
\nAuthorization Requirements:
\nTarget Company: Administrator role required
\nThe user must have administrative access to the company that owns the document
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nDocument with specified ID must exist
\nDocument must belong to the specified company
\nDocument ID must be a valid numeric value
\nUse Cases:
\nRemoving outdated or incorrect documents
\nDeleting expired contracts or certificates
\nCleaning up unnecessary documentation
\nCompliance with document retention policies
\nReplacing documents with updated versions
\nImportant Notes:
\nPermanent Action: This operation cannot be undone through the API
\nFile Removal: Associated document files are permanently deleted from server storage
\nContract Flag Management: Automatic contract status management based on remaining contract documents
\nAudit Trail: The deletion action may be logged for audit and compliance purposes
\nSpecial Contract Handling:
\nWhen a contract document is deleted:
\nThe system checks all remaining documents for the company
\nIf no other documents of type \"Contract\" are found
\nThe company's contract flag is automatically set to false
This affects the company's contract status in the system
\nSecurity Considerations:
\nOnly users with Administrator role in the company can delete documents
\nThe system validates that the document belongs to the specified company
\nCross-company document deletion is not permitted
\nDocument ID must be numeric to prevent injection attacks
\nRelated Operations:
\nAfter deleting a document, you may want to:
\nUpload a new document if replacement is needed
\nReview remaining documents for the company
\nVerify the company's contract status if a contract was deleted
\nUpdate related compliance documentation
\nError Scenarios:
\nInvalid Document ID: When the ID is not numeric
\nDocument Not Found: When the ID doesn't exist or doesn't belong to the company
\nInsufficient Permissions: When user lacks Administrator role
\nCompany Not Found: When the company UUID is invalid
\nSystem Errors: When database or file system issues occur
\nDocument Types Affected:
\nContract - Legal contracts (affects company contract flag)
Commercial Register - Commercial registration documents
Identity document legal representative - ID documents
Billing instructions or information - Billing documents
Other - Any other type of company document
Compliance Considerations:
\nEnsure proper backup of documents before deletion if required by regulations
\nVerify that deletion doesn't violate document retention policies
\nConsider the impact on ongoing business processes
\nMaintain audit records of document deletion activities
\nAdd a tax certificate to a company.
\n\n\nThis endpoint allows adding a tax certificate to a specific company. Tax certificates are country-specific documents that validate the company's tax status in particular jurisdictions. The authenticated user must have Administrator role in the specified company. All parameters are mandatory for this endpoint.
\n
URL Path Parameter:
\n{key} - Company UUID key\n\nRequest Body Parameters:
\n{\n \"countryCode\": \"DE\",\n \"validFrom\": \"2024-03-04\",\n \"validTo\": \"2024-03-09\",\n \"fileName\": \"ABC.pdf\",\n \"fileContent\": \"\"\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Tax certificate created successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Invalid country code: XX\"\n}\n\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Invalid date format or validation error\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nRequest Body Parameters Description:
\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\ncountryCode must be a valid 2-letter ISO country code existing in the system
validFrom and validTo must be in YYYY-MM-DD format
validTo should be later than or equal to validFrom (logical date validation)
Both fileName and fileContent are mandatory
fileContent must be valid base64 encoded data
The system automatically sets time components: valid_from to 00:00:00 and valid_to to 23:59:59
\nCertificate files are stored with a unique naming convention
\nFile Upload Details:
\nFile Storage Location: Company-specific directory on the server
\nFile Naming Convention: TAX_CERTIFICATE_{companyId}_{countryCode}_{YYYY-DD-HHMMSS}.{originalExtension}
Supported Formats: Any file format with proper extension in filename
\nFile Processing: Base64 content is decoded and stored as binary file
\nDirectory Creation: System automatically creates company directory if it doesn't exist
\nDate Processing:
\nvalid_from: Converted to YYYY-MM-DD 00:00:00 format
valid_to: Converted to YYYY-MM-DD 23:59:59 format
Input Format: Must be provided as YYYY-MM-DD
Validation: Dates must be valid calendar dates
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nCompany must exist and be accessible to the user
\nValid country code must be provided
\nValid date range must be specified
\nValid certificate document must be provided
\nUse Cases:
\nAdding tax residency certificates for international operations
\nStoring VAT certificates for specific countries
\nMaintaining compliance documentation for cross-border business
\nSupporting VAT claim filing requirements
\nEstablishing tax status for regulatory purposes
\nExample File Naming:
\nFor a German tax certificate uploaded on March 15, 2024, the system would generate:
\nTAX_CERTIFICATE_12345_DE_2024-15-103045.pdf\n\nCommon Country Codes:
\nDE - Germany
FR - France
GB - United Kingdom
US - United States
IT - Italy
ES - Spain
NL - Netherlands
AT - Austria
Related Information:
\nTax certificates are used to:
\nValidate company tax status in specific jurisdictions
\nSupport VAT registration and claim processes
\nMeet compliance requirements for international business
\nProvide evidence of tax obligations and rights
\nSupport audit and regulatory review processes
\nDelete a company tax certificate.
\n\n\nThis endpoint allows removing an existing tax certificate for a specific company. This action permanently removes the tax certificate and its associated documentation. The authenticated user must have Administrator role in the target company.
\n
URL Path Parameters:
\n{key} - Company UUID key\n{id} - Tax certificate ID\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Tax certificate deleted successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Tax certificate with id {id} not found for this company\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the target company
\nThe tax certificate with the specified id must exist and belong to the company
The certificate entry must be associated with the specified company
\nThe deletion is permanent and cannot be undone through the API
\nAssociated certificate files may be removed from the server storage
\nAll validity periods and country associations for this certificate are removed
\nAuthorization Requirements:
\nTarget Company: Administrator role required
\nThe user must have administrative access to the company that owns the tax certificate
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nTax certificate with specified ID must exist
\nTax certificate must belong to the specified company
\nUse Cases:
\nRemoving expired tax certificates
\nDeleting invalid or incorrect certificates
\nCleaning up outdated tax documentation
\nCompliance with document retention policies
\nReplacing certificates with updated versions
\nImportant Notes:
\nPermanent Action: This operation cannot be undone through the API
\nFile Removal: Associated certificate files may be permanently deleted from server storage
\nCompliance Impact: Removing certificates may affect VAT filing capabilities in specific countries
\nAudit Trail: The deletion action may be logged for audit and compliance purposes
\nSecurity Considerations:
\nOnly users with Administrator role in the company can delete tax certificates
\nThe system validates that the tax certificate belongs to the specified company
\nCross-company certificate deletion is not permitted
\nDeletion requires proper authentication and authorization
\nRelated Operations:
\nAfter deleting a tax certificate, you may want to:
\nUpload a new certificate if replacement is needed
\nReview remaining certificates for the company
\nVerify VAT filing capabilities for affected countries
\nUpdate compliance documentation as needed
\nError Scenarios:
\nCertificate Not Found: When the ID doesn't exist or doesn't belong to the company
\nInsufficient Permissions: When user lacks Administrator role
\nCompany Not Found: When the company UUID is invalid
\nSystem Errors: When database or file system issues occur
\nCompliance Considerations:
\nEnsure proper backup of certificates before deletion if required by regulations
\nVerify that deletion doesn't violate document retention policies
\nConsider the impact on ongoing VAT processes and claims
\nMaintain audit records of certificate deletion activities
\nRetrieve representatives for a company.
\n\n\nThis endpoint allows retrieving all representatives associated with a specific company. Representatives are entities that can act on behalf of the company when filing VAT claims in various countries. The authenticated user must have Administrator role in the specified company to access this information.
\n
URL Path Parameter:
\n{key} - Company UUID key\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"representatives\": [\n {\n \"id\": 789,\n \"companyId\": 12345,\n \"legalName\": \"VAT Representative Services Ltd\",\n \"contactPerson\": \"John Smith\",\n \"poaFileName\": \"POA18883_8720_2025-0505-171438.pdf\",\n \"createdAt\": \"2025-05-05 05:14:38\",\n \"modifiedAt\": \"2025-05-05 17:14:38\",\n \"userId\": 123,\n \"modifiedBy\": null,\n \"representativeLegalName\": \"My Client\",\n \"modifiedByUserName\": null,\n \"countries\": [\n {\n \"name\": \"Germany\",\n \"code\": \"DE\"\n },\n {\n \"name\": \"France\", \n \"code\": \"FR\"\n }\n ]\n }\n ]\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Error description\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nURL Parameters Description:
\nResponse Fields Description:
\nRepresentative Object Fields:
\nCountry Object Fields (within countries array):
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the specified company
\nOnly representatives belonging to the specified company are returned
\nEach representative includes the list of countries where they can act on behalf of the company
\nCountry information is returned with both full name and ISO short code
\nIf no representatives exist for the company, an empty array is returned
\nRepresentatives can only be accessed by users who have appropriate permissions
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nCompany must exist and be accessible to the user
\nUse Cases:
\nDisplaying available representatives for VAT claim filing
\nManaging company representation across different countries
\nAuditing representative relationships and authorizations
\nSelecting appropriate representative based on claim destination country
\nCompliance reporting for cross-border VAT operations
\nRelated Information:
\nRepresentatives are used during VAT claim creation to specify which entity will handle the claim filing process in the destination country. Each representative must have:
\nA valid Power of Attorney (POA) document
\nAuthorization for specific countries
\nAn active company profile in the VAT4U system
\nProper permissions setup for the requesting user
\nAdd a representative to a company.
\n\n\nThis endpoint allows adding a new representative to a specific company. Representatives are entities that can act on behalf of the company when filing VAT claims in various countries. The authenticated user must have Administrator role in both the target company and the representative company. A Power of Attorney (POA) document must be uploaded as part of the process.
\n
URL Path Parameter:
\n{key} - Company UUID key\n\nRequest Body Parameters:
\n{\n \"representativeKey\": \"661ca9b7-95e0-4c10-96d4-237719f14100\",\n \"countries\": [\"DE\", \"PL\"],\n \"contactPerson\": \"Max Mustermann\",\n \"fileName\": \"POA.pdf\",\n \"fileContent\": \"\"\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Representative created successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Error description\"\n}\n\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Invalid country code: XX\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nRequest Body Parameters Description:
\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the target company
\nThe authenticated user must have Administrator role in the representative company (or at least access to it)
\nThe representativeKey must reference an existing company in the VAT4U system
All country codes in the countries array must be valid 2-letter ISO country codes existing in the system
Both fileName and fileContent are mandatory for POA document upload
The POA file is stored with a unique naming convention: POA{companyId}_{representativeId}_{timestamp}.{extension}
File content must be valid base64 encoded data
\nThe representative company cannot represent itself
\nCountry codes are validated against the system's country database
\nFile Upload Details:
\nFile Storage Location: Company-specific directory on the server
\nFile Naming Convention: POA{companyId}_{representativeId}_{YYYY-DD-HHMMSS}.{originalExtension}
Supported Formats: Any file format with proper extension in filename
\nFile Processing: Base64 content is decoded and stored as binary file
\nDirectory Creation: System automatically creates company directory if it doesn't exist
\nAuthorization Requirements:
\nThe user must have appropriate permissions for both companies involved:
\nTarget Company: Administrator role required
\nRepresentative Company: User must have access (checked during validation)
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nUser must have access to the representative company
\nRepresentative company must exist and be active in the system
\nValid country codes must be provided
\nValid POA document must be provided
\nSufficient server storage space for file upload
\nUse Cases:
\nSetting up VAT claim representatives for cross-border operations
\nEstablishing legal representation in specific countries
\nCompliance with local VAT filing requirements
\nDelegating VAT claim filing authority to specialized service providers
\nRelated Information:
\nRepresentatives can be used during VAT claim creation to specify which entity will handle the filing
\nEach representative relationship is country-specific
\nPOA documents serve as legal authorization for representation
\nRepresentatives must be existing companies within the VAT4U platform
\nMultiple representatives can be added for different countries or regions
\nExample Country Codes:
\nDE - Germany
PL - Poland
FR - France
GB - United Kingdom
ES - Spain
IT - Italy
NL - Netherlands
Update a company representative.
\n\n\nThis endpoint allows updating an existing representative relationship for a specific company. Representatives are entities that can act on behalf of the company when filing VAT claims in various countries. The authenticated user must have Administrator role in both the target company and the representative company. All parameters are optional - only provided fields will be updated.
\n
URL Path Parameters:
\n{key} - Company UUID key\n{id} - Representative relationship ID\n\nRequest Body Parameters:
\n{\n \"representativeKey\": \"661ca9b7-95e0-4c10-96d4-237719f14100\",\n \"countries\": [\"DE\", \"PL\"],\n \"contactPerson\": \"Max Mustermann\",\n \"fileName\": \"POA.pdf\",\n \"fileContent\": \"\"\n}\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Representative created successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Representative with id {id} not found for this company\"\n}\n\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Invalid country code: XX\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nRequest Body Parameters Description:
\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the target company
\nThe authenticated user must have Administrator role in the representative company (or at least access to it)
\nThe representative relationship with the specified id must exist and belong to the company
If representativeKey is provided, it must reference an existing company in the VAT4U system
All country codes in the countries array must be valid 2-letter ISO country codes existing in the system
If POA document fields are provided, both fileName and fileContent must be specified together
Only provided fields will be updated; missing fields will retain their current values
\nIf a new POA file is uploaded, it will replace the existing one
\nUpdate Behavior:
\nPartial Updates: Only fields provided in the request will be updated
\nField Retention: Fields not included in the request will keep their existing values
\nFile Replacement: Uploading a new POA file completely replaces the existing file
\nCountry Override: Providing a new countries array completely replaces the existing country list
\nRepresentative Change: Changing representativeKey transfers the relationship to a different company
File Upload Details:
\nFile Storage Location: Company-specific directory on the server
\nFile Naming Convention: POA{companyId}_{representativeId}_{YYYY-DD-HHMMSS}.{originalExtension}
File Processing: Base64 content is decoded and stored as binary file
\nFile Replacement: New uploads overwrite existing POA files
\nAuthorization Requirements:
\nThe user must have appropriate permissions for both companies involved:
\nTarget Company: Administrator role required
\nRepresentative Company: User must have access (checked during validation)
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nUser must have access to the representative company (if changing representative)
\nRepresentative relationship with specified ID must exist
\nRepresentative company must exist and be active in the system (if changing representative)
\nValid country codes must be provided (if updating countries)
\nValid POA document must be provided (if updating file)
\nUse Cases:
\nUpdating contact person information for existing representative
\nModifying country authorization scope for representative
\nReplacing expired or updated Power of Attorney documents
\nChanging the representative company while maintaining the relationship
\nAdjusting representative permissions for specific countries
\nExample Update Scenarios:
\nUpdate Contact Person Only:
\n{\n \"contactPerson\": \"John Smith\"\n}\n\nUpdate Countries Only:
\n{\n \"countries\": [\"DE\", \"FR\", \"IT\"]\n}\n\nReplace POA Document:
\n{\n \"fileName\": \"Updated_POA.pdf\",\n \"fileContent\": \"base64_encoded_content_here\"\n}\n\nDelete a company representative.
\n\n\nThis endpoint allows removing an existing representative relationship for a specific company. This action permanently removes the representative's authorization to act on behalf of the company for VAT claims. The authenticated user must have Administrator role in the target company.
\n
URL Path Parameters:
\n{key} - Company UUID key\n{id} - Representative relationship ID\n\nSuccess Response (HTTP 200 OK):
\n{\n \"status\": \"success\",\n \"data\": {\n \"message\": \"Representative deleted successfully\"\n }\n}\n\nError Responses:
\nHTTP 400 Bad Request:
\n{\n \"status\": \"error\",\n \"code\": \"ERROR_CODE\",\n \"message\": \"Representative with id {id} not found for this company\"\n}\n\nHTTP 401 Unauthorized:
\n{\n \"status\": \"error\",\n \"code\": \"Unauthorized\",\n \"message\": \"You don't have enough permissions for this action.\"\n}\n\nHTTP 500 Internal Server Error:
\n{\n \"status\": \"error\",\n \"code\": \"\",\n \"message\": \"\"\n}\n\nURL Parameters Description:
\nBusiness Rules and Validation:
\nThe authenticated user must have Administrator role in the target company
\nThe representative relationship with the specified id must exist and belong to the company
The representative entry must be associated with the specified company
\nThe deletion is permanent and cannot be undone through the API
\nAll country authorizations for this representative relationship are removed
\nAssociated Power of Attorney documents remain stored but are no longer linked
\nAuthorization Requirements:
\nTarget Company: Administrator role required
\nThe user must have administrative access to the company that owns the representative relationship
\nPrerequisites:
\nUser authentication is required
\nUser must have Administrator role in the target company
\nRepresentative relationship with specified ID must exist
\nRepresentative relationship must belong to the specified company
\nUse Cases:
\nTerminating representative services
\nRemoving expired or invalid representative relationships
\nCleaning up unused representative authorizations
\nCompliance with changing business requirements
\nRevoking representative access after contract termination
\nImportant Notes:
\nPermanent Action: This operation cannot be undone through the API
\nFile Retention: POA documents may remain on the server but will no longer be accessible through the representative relationship
\nClaim Impact: Existing VAT claims that used this representative will not be affected, but future claims cannot use this representative
\nAudit Trail: The deletion action may be logged for audit purposes
\nSecurity Considerations:
\nOnly users with Administrator role in the company can delete representatives
\nThe system validates that the representative relationship belongs to the specified company
\nCross-company representative deletion is not permitted
\nRelated Operations:
\nAfter deleting a representative, you may want to:
\nList remaining representatives using the List Representatives endpoint
\nAdd a new representative if replacement is needed
\nReview VAT claims that were filed through the deleted representative
\nError Scenarios:
\nRepresentative Not Found: When the ID doesn't exist or doesn't belong to the company
\nInsufficient Permissions: When user lacks Administrator role
\nCompany Not Found: When the company UUID is invalid
\nSystem Errors: When database or file system issues occur
\nRetrieve list of claims from the platform.
\n\n\nThis endpoint has pagination. Pay attention to the page URL query parameter. If you omit this parameter API will return all companies from your profile. Hint: This is useful if you would like to retrieve all the records in a single API call.
\n
companyIdclaimantKey: String (optional) - Filter single claimant claims. Use \"key\" property from the Companies API\npage: Number (optional) - Page to be returned when using pagination. If ommited system will return first 10.000 records.\nmodifiedAfter: Date (optional) use to filter entities that have modifiedAt date after the specified date (format YYYY-MM-DD)\n\n{\n \"status\": \"success\",\n \"data\": [{List of claims}],\n \"pagination\": {\n \"totalRecords\": {Total number of claims},\n \"currentPage\": {Returned page},\n \"perPage\": {Number of claims per page},\n \"totalPages\": {Total number of pages in the API}\n }\n}\n\nSingle claim object:
\n{\n \"id\": 123456,\n \"claimCode\": \"\",\n \"createdAt\": \"2023-12-02 08:02:14\",\n \"claimedDateExchangeRate\": 0.2311,\n \"claimedNotifficationSentAt\": \"2023-12-04 08:02:14\",\n \"claimType\": \"CLAIM_TO_TAX_ADMINISTRATION\",\n \"createdBy\": {\n \"id\": 465,\n \"firstName\": \"Demo\",\n \"lastName\": \"User\",\n \"email\": \"test@vat4u.com\"\n },\n \"cor\": {\n \"id\": 3,\n \"code\": \"CZ\",\n \"name\": \"Czech Republic\"\n },\n \"currency\": {\n \"code\": \"CZK\",\n \"name\": \"Czech Kurony\"\n },\n \"claimant\": {\n \"id\": 2,\n \"legalName\": \"Demo 2\"\n },\n \"claimantEmail\": \"test-claims@vat4u.com\",\n \"period\": \"01/22 - 12/22\",\n \"startDate\": \"2022-01-01 00:00:00\",\n \"endDate\": \"2022-12-31 00:00:00\",\n \"referenceCode\": \"\",\n \"confirmedReceptionByTaxAdministration\": false,\n \"netTotal\": 29648.95,\n \"vatTotal\": 2082.65,\n \"potentialCashback\": 2082.65,\n \"expensesPurpose\": \"\",\n \"representative\": null,\n \"hasAttachment\": false,\n \"refundTo\": \"applicant\",\n \"bankAccount\": {\n \"id\": 7112,\n \"internalName\": \"Test\",\n \"bankAddress\": \"Test\",\n \"bankName\": \"Test\",\n \"iban\": \"Test\",\n \"bic\": \"Test\",\n \"accountNumber\": \"Test\",\n \"accountHolderName\": \"Test\",\n \"accountHolderAddress\": \"Test\",\n \"createdAt\": \"2023-03-28 01:05:31\",\n \"createdBy\": 465\n },\n \"isVerified\": false,\n \"verifiedByUser\": null,\n \"verifiedAt\": null,\n \"declaration\": false,\n \"approvedAmount\": 2082.65,\n \"approvedDate\": \"2023-03-01 00:00:00\",\n \"approvedDateExchangeRate\": 0.3306,\n \"approvedEur\": 6299.61,\n \"potentialClaimFee\": 104.13,\n \"claimFee\": 314.98,\n \"submittedAt\": null,\n \"claimAccountingPeriodYear\": null,\n \"claimAccountingPeriodMonth\": null,\n \"totalExpensesCount\": \"55\",\n \"claimOutputCurrencyCode\": null,\n \"claimOutputFxRate\": 1,\n \"refundStatus\": {\n \"code\": \"APPROVED\",\n \"title\": \"Approved\"\n },\n \"vatFlowStatus\": {\n \"code\": \"DOMESTIC\",\n \"title\": \"Domestic\"\n },\n \"nextStageStatus\": {\n \"code\": \"ARCHIVED\",\n \"title\": \"Archived\"\n },\n \"approvalRate\": {\n \"totalDeductibleAmount\": 2082.65,\n \"totalApprovedAmount\": 2082.65\n },\n \"modifiedAt\": \"2023-02-14 14:54:11\",\n \"parentClaim\": null,\n \"childClaims\": []\n }\n\nSingle claim object fields description
\nUser object
\nClaim status object (Refund, VAT Flow, Next stage)
\nCountry refund of the claim
\nCurrency of the claim
\nClaimant of the claim (Reference to the Company API)
\nBank account details linked to the claim
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}},"urlObject":{"path":["v1","claims"],"host":["https://api.vat4u.com"],"query":[{"key":"claimantKey","value":"5b94dea4-4eb1-4943-a742-a92c35b6cf10"},{"key":"page","value":"0"},{"key":"modifiedAfter","value":"2023-02-02"}],"variable":[]}},"response":[{"id":"9c3a2b1b-5b00-496f-af7b-cd849e13a091","name":"Successful response","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.vat4u.com/v1/claims?claimantKey=5b94dea4-4eb1-4943-a742-a92c35b6cf10&page=0&modifiedAfter=2023-02-02","host":["https://api.vat4u.com"],"path":["v1","claims"],"query":[{"key":"claimantKey","value":"5b94dea4-4eb1-4943-a742-a92c35b6cf10"},{"key":"page","value":"0"},{"key":"modifiedAfter","value":"2023-02-02"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method"},{"key":"Access-Control-Allow-Methods","value":"GET, POST"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Content-Encoding","value":"gzip"},{"key":"Content-Length","value":"927"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Tue, 23 Apr 2024 14:14:29 GMT"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Pragma","value":"no-cache"},{"key":"Server","value":"Apache/2.4.41 (Ubuntu)"},{"key":"Set-Cookie","value":"ci_session=a5ed9lsg5kahjf30h4rv6tec79o5tsbf; expires=Tue, 23-Apr-2024 14:44:29 GMT; Max-Age=1800; path=/; domain=.app.vat4u.local; secure; HttpOnly; SameSite=Lax"},{"key":"Vary","value":"Accept-Encoding"},{"key":"X-Powered-By","value":"PHP/7.4.33"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": [\n {\n \"id\": 6155,\n \"key\": \"9c3cf2cd-c3ab-428d-85a2-fa968f763fad\",\n \"createdAt\": \"2024-03-05 16:08:41\",\n \"claimedDateExchangeRate\": 10,\n \"claimedNotifficationSentAt\": null,\n \"claimType\": \"CLAIM_TO_TAX_ADMINISTRATION\",\n \"createdBy\": {\n \"id\": 465,\n \"firstName\": \"Demo\",\n \"lastName\": \"User\",\n \"email\": \"test@vat4u.com\"\n },\n \"cor\": {\n \"id\": 9,\n \"code\": \"ES\",\n \"name\": \"Spain\"\n },\n \"currency\": {\n \"code\": \"EUR\",\n \"name\": \"Euro\"\n },\n \"claimant\": {\n \"id\": 2,\n \"legalName\": \"Demo2\",\n \"key\": \"5b94dea4-4eb1-4943-a742-a92c35b6cf10\"\n },\n \"claimantEmail\": \"test-claims@vat4u.com\",\n \"period\": \"01/23 - 12/23\",\n \"startDate\": \"2023-01-01 00:00:00\",\n \"endDate\": \"2023-12-31 00:00:00\",\n \"referenceCode\": \"\",\n \"confirmedReceptionByTaxAdministration\": false,\n \"netTotal\": 123.97,\n \"vatTotal\": 26.03,\n \"potentialCashback\": 26.03,\n \"expensesPurpose\": \"\",\n \"representative\": null,\n \"hasAttachment\": false,\n \"refundTo\": \"applicant\",\n \"bankAccount\": {\n \"id\": 7115,\n \"internalName\": \"Test\",\n \"bankAddress\": \"test\",\n \"bankName\": \"test\",\n \"iban\": \"TESY\",\n \"bic\": \"TEST\",\n \"accountNumber\": \"test\",\n \"accountHolderName\": \"test\",\n \"accountHolderAddress\": \"test\",\n \"createdAt\": \"2024-01-25 10:23:59\",\n \"createdBy\": 465\n },\n \"isVerified\": true,\n \"verifiedByUser\": 465,\n \"verifiedAt\": \"2024-04-23 12:23:54\",\n \"declaration\": true,\n \"approvedAmount\": 26.03,\n \"approvedDate\": \"2024-03-19 00:36:34\",\n \"approvedDateExchangeRate\": 10,\n \"approvedEur\": 2.6,\n \"potentialClaimFee\": 0,\n \"claimFee\": 0,\n \"submittedAt\": null,\n \"claimAccountingPeriodYear\": null,\n \"claimAccountingPeriodMonth\": null,\n \"totalExpensesCount\": \"1\",\n \"claimOutputCurrencyCode\": \"EUR\",\n \"claimOutputFxRate\": 1,\n \"refundStatus\": {\n \"code\": \"EXCLUDED\",\n \"title\": \"Excluded\"\n },\n \"vatFlowStatus\": {\n \"code\": \"FOREIGN_8TH\",\n \"title\": \"Foreign - 8th\"\n },\n \"nextStageStatus\": {\n \"code\": \"ARCHIVED\",\n \"title\": \"Archived\"\n },\n \"approvalRate\": {\n \"totalDeductibleAmount\": 26.03,\n \"totalApprovedAmount\": 26.03\n },\n \"modifiedAt\": \"2024-04-23 12:28:27\",\n \"parentClaim\": null,\n \"childClaims\": []\n }\n ],\n \"pagination\": {\n \"totalRecords\": 1,\n \"currentPage\": 0,\n \"perPage\": 25,\n \"totalPages\": 1\n }\n}"}],"_postman_id":"d312acd8-f5f7-474b-8b5e-769d71bb9343"},{"name":"Single claim","id":"f40429aa-cca3-41ac-a927-ff0490d5d3ac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.vat4u.com/v1/claims/:claimKey","description":"Retrieve single claim by KEY.
\nPath parameters:
\nInclude claim \"key\" from the list of claims to retrieve a single claim data.\n\nResponse:
\n{\n \"status\": \"success\",\n \"data\": [{Claim object}],\n}\nResponse:\n``` json\n{\n \"status\": \"success\",\n \"data\": [{Claim object}]\n }\n}\n\nSingle claim object:
\n{\n \"id\": 123456,\n \"claimCode\": \"\",\n \"createdAt\": \"2023-12-02 08:02:14\",\n \"claimedDateExchangeRate\": 0.2311,\n \"claimedNotifficationSentAt\": \"2023-12-04 08:02:14\",\n \"claimType\": \"CLAIM_TO_TAX_ADMINISTRATION\",\n \"createdBy\": {\n \"id\": 465,\n \"firstName\": \"Demo\",\n \"lastName\": \"User\",\n \"email\": \"test@vat4u.com\"\n },\n \"cor\": {\n \"id\": 3,\n \"code\": \"CZ\",\n \"name\": \"Czech Republic\"\n },\n \"currency\": {\n \"code\": \"CZK\",\n \"name\": \"Czech Kurony\"\n },\n \"claimant\": {\n \"id\": 2,\n \"legalName\": \"Demo 2\"\n },\n \"claimantEmail\": \"test-claims@vat4u.com\",\n \"period\": \"01/22 - 12/22\",\n \"startDate\": \"2022-01-01 00:00:00\",\n \"endDate\": \"2022-12-31 00:00:00\",\n \"referenceCode\": \"\",\n \"confirmedReceptionByTaxAdministration\": false,\n \"netTotal\": 29648.95,\n \"vatTotal\": 2082.65,\n \"potentialCashback\": 2082.65,\n \"expensesPurpose\": \"\",\n \"representative\": null,\n \"hasAttachment\": false,\n \"refundTo\": \"applicant\",\n \"bankAccount\": {\n \"id\": 7112,\n \"internalName\": \"Test\",\n \"bankAddress\": \"Test\",\n \"bankName\": \"Test\",\n \"iban\": \"Test\",\n \"bic\": \"Test\",\n \"accountNumber\": \"Test\",\n \"accountHolderName\": \"Test\",\n \"accountHolderAddress\": \"Test\",\n \"createdAt\": \"2023-03-28 01:05:31\",\n \"createdBy\": 465\n },\n \"isVerified\": false,\n \"verifiedByUser\": null,\n \"verifiedAt\": null,\n \"declaration\": false,\n \"approvedAmount\": 2082.65,\n \"approvedDate\": \"2023-03-01 00:00:00\",\n \"approvedDateExchangeRate\": 0.3306,\n \"approvedEur\": 6299.61,\n \"potentialClaimFee\": 104.13,\n \"claimFee\": 314.98,\n \"submittedAt\": null,\n \"claimAccountingPeriodYear\": null,\n \"claimAccountingPeriodMonth\": null,\n \"totalExpensesCount\": \"55\",\n \"claimOutputCurrencyCode\": null,\n \"claimOutputFxRate\": 1,\n \"refundStatus\": {\n \"code\": \"APPROVED\",\n \"title\": \"Approved\"\n },\n \"vatFlowStatus\": {\n \"code\": \"DOMESTIC\",\n \"title\": \"Domestic\"\n },\n \"nextStageStatus\": {\n \"code\": \"ARCHIVED\",\n \"title\": \"Archived\"\n },\n \"approvalRate\": {\n \"totalDeductibleAmount\": 2082.65,\n \"totalApprovedAmount\": 2082.65\n },\n \"modifiedAt\": \"2023-02-14 14:54:11\",\n \"parentClaim\": null,\n \"childClaims\": []\n }\n\nSingle claim object fields description
\nUser object
\nClaim status object (Refund, VAT Flow, Next stage)
\nCountry refund of the claim
\nCurrency of the claim
\nClaimant of the claim (Reference to the Company API)
\nBank account details linked to the claim
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}},"urlObject":{"path":["v1","claims",":claimKey"],"host":["https://api.vat4u.com"],"query":[],"variable":[{"type":"any","value":"","key":"claimKey"}]}},"response":[{"id":"823af695-856a-4606-95a6-f80f800cb752","name":"Successful response","originalRequest":{"method":"GET","header":[],"url":"https://api.vat4u.com/v1/claims/9c3cf2cd-c3ab-428d-85a2-fa968f763fad"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method"},{"key":"Access-Control-Allow-Methods","value":"GET, POST"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Content-Encoding","value":"gzip"},{"key":"Content-Length","value":"890"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Tue, 23 Apr 2024 14:21:29 GMT"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Pragma","value":"no-cache"},{"key":"Server","value":"Apache/2.4.41 (Ubuntu)"},{"key":"Set-Cookie","value":"ci_session=mfv1ekt8jp2jv0a9r9h7ep3g4vgif38a; expires=Tue, 23-Apr-2024 14:51:29 GMT; Max-Age=1800; path=/; domain=.app.vat4u.local; secure; HttpOnly; SameSite=Lax"},{"key":"Vary","value":"Accept-Encoding"},{"key":"X-Powered-By","value":"PHP/7.4.33"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": {\n \"id\": 6155,\n \"key\": \"9c3cf2cd-c3ab-428d-85a2-fa968f763fad\",\n \"createdAt\": \"2024-03-05 16:08:41\",\n \"claimedDateExchangeRate\": 10,\n \"claimedNotifficationSentAt\": null,\n \"claimType\": \"CLAIM_TO_TAX_ADMINISTRATION\",\n \"createdBy\": {\n \"id\": 465,\n \"firstName\": \"Demo\",\n \"lastName\": \"User\",\n \"email\": \"test@vat4u.com\"\n },\n \"cor\": {\n \"id\": 9,\n \"code\": \"ES\",\n \"name\": \"Spain\"\n },\n \"currency\": {\n \"code\": \"EUR\",\n \"name\": \"Euro\"\n },\n \"claimant\": {\n \"id\": 2,\n \"legalName\": \"Demo2\",\n \"key\": \"5b94dea4-4eb1-4943-a742-a92c35b6cf10\"\n },\n \"claimantEmail\": \"test-claims@vat4u.com\",\n \"period\": \"01/23 - 12/23\",\n \"startDate\": \"2023-01-01 00:00:00\",\n \"endDate\": \"2023-12-31 00:00:00\",\n \"referenceCode\": \"\",\n \"confirmedReceptionByTaxAdministration\": false,\n \"netTotal\": 123.97,\n \"vatTotal\": 26.03,\n \"potentialCashback\": 26.03,\n \"expensesPurpose\": \"\",\n \"representative\": null,\n \"hasAttachment\": false,\n \"refundTo\": \"applicant\",\n \"bankAccount\": {\n \"id\": 7115,\n \"internalName\": \"Test\",\n \"bankAddress\": \"test\",\n \"bankName\": \"test\",\n \"iban\": \"TESY\",\n \"bic\": \"TEST\",\n \"accountNumber\": \"test\",\n \"accountHolderName\": \"test\",\n \"accountHolderAddress\": \"test\",\n \"createdAt\": \"2024-01-25 10:23:59\",\n \"createdBy\": 465\n },\n \"isVerified\": true,\n \"verifiedByUser\": 465,\n \"verifiedAt\": \"2024-04-23 12:23:54\",\n \"declaration\": true,\n \"approvedAmount\": 26.03,\n \"approvedDate\": \"2024-03-19 00:36:34\",\n \"approvedDateExchangeRate\": 10,\n \"approvedEur\": 2.6,\n \"potentialClaimFee\": 0,\n \"claimFee\": 0,\n \"submittedAt\": null,\n \"claimAccountingPeriodYear\": null,\n \"claimAccountingPeriodMonth\": null,\n \"totalExpensesCount\": \"1\",\n \"claimOutputCurrencyCode\": \"EUR\",\n \"claimOutputFxRate\": 1,\n \"refundStatus\": {\n \"code\": \"EXCLUDED\",\n \"title\": \"Excluded\"\n },\n \"vatFlowStatus\": {\n \"code\": \"FOREIGN_8TH\",\n \"title\": \"Foreign - 8th\"\n },\n \"nextStageStatus\": {\n \"code\": \"ARCHIVED\",\n \"title\": \"Archived\"\n },\n \"approvalRate\": {\n \"totalDeductibleAmount\": 26.03,\n \"totalApprovedAmount\": 26.03\n },\n \"modifiedAt\": \"2024-04-23 12:28:27\",\n \"parentClaim\": null,\n \"childClaims\": []\n }\n}"}],"_postman_id":"f40429aa-cca3-41ac-a927-ff0490d5d3ac"}],"id":"93b31c6c-69c0-413c-9688-17d5fc27d2e0","_postman_id":"93b31c6c-69c0-413c-9688-17d5fc27d2e0","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}}},{"name":"Category","item":[{"name":"List categories","id":"12ae9cb7-bf39-4093-8bfc-cdb7df556004","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.vat4u.com/v1/categories/:countryCode","description":"This endpoint retrieves a list of expense categories from VAT4U.
\nPath parameter indicating shortcode for country to retrieve country specific categories. If ommited, API will return complete list of available categories. Note: some categories might not be active in all the countries.
\nTo check the active categories for specific country, provide a country code in the path.
\nThe response will include a JSON object containing the following key:
\ncategories: An array of categories.
country: Country details if list of categories is retrieved for specific country.
Ensure that you have the necessary permissions to access this endpoint.
\nThe response may vary based on the user's access level and the data available in the system.
\nThis endpoint retrieves a category mapping stored in the system.
\ncategoryMappingId should be provided in the path.
The response will include a JSON object containing the following keys:
\nname - Name of the mapping to be identified in the application UI when importing the data.
mapping: An array of objects, each containing details relevant to mapping of User category to VAT4U system expense category.
user: User category from the 3rd party system
system: VAT4U system category
countries: Specific system category for each country (in case country requires special split)
Purpose:
This GET request retrieves a list of webhooks configured for a specific company. Use this endpoint to view all webhook subscriptions associated with the provided company.
Path Variable:
\ncompanyId (string, optional): The unique identifier of the company whose webhooks you want to list. If not supplied, all webhooks from companies where API user has access will be retrieved.Purpose:
Creates a new webhook for a specified company. Webhooks allow your application to receive real-time notifications about specific events (e.g., when an expense compliance check is finished).
Request Body:
\n {\n \"companyId\": \"string\", // Required. The unique identifier of the company.\n \"aggregateClients\": \"bool\" // Optional. If enabled, the webhook will receive events for all clients of the company.\n \"url\": \"string\", // Required. The endpoint to receive webhook events.\n \"events\": [\"string\"], // Required. List of event types to subscribe to.\n \"name\": \"string\" // Optional. Name for the webhook.\n }\n\nExample:
\n {\n \"companyId\": \"5b94dea4-4eb1-4943-a742-a92c35b6cf10\",\n \"url\": \"https://webhook.example.com/123\",\n \"events\": [\"expense.compliance_check_finished\"],\n \"name\": \"Webhook test\"\n }\n\nExpected Response:
\nStatus: 200 OK
Body Example:
\n {\n \"id\": 21,\n \"name\": \"Webhook test\",\n \"url\": \"https://webhook.example.com/123\",\n \"events\": [\"expense.compliance_check_finished\"],\n \"status\": \"active\",\n \"lastEventAt\": null,\n \"secret\": \"<webhook_secret>\"\n }\n\nImportant Notes:
\nThe secret in the response should be securely stored; it is used to verify the authenticity of webhook events. It is returned only uppon creation of the webhook and cannot be retrieved again.
The events array determines which event types will trigger the webhook. Currently the following events are available:
company.created
company.updated
expense.created
expense.updated
expense.compliance_check_finished
expense.compliance_check_failed
expense.data_verification_finished
expense.data_verification_failed
expense.smart_ai_finished
expense.smart_ai_failed
Purpose:
This GET request retrieves a list of webhooks configured for a specific company. Use this endpoint to view all webhook subscriptions associated with the provided company.
Path Variable:
\ncompanyId (string, optional): The unique identifier of the company whose webhooks you want to list. If not supplied, all webhooks from companies where API user has access will be retrieved.This request deletes a specific webhook from the system using its unique identifier.
\nUse this endpoint to permanently remove a webhook that is no longer needed. Deleting a webhook will stop all future event notifications from being sent to the webhook's configured URL.
\nThis action is irreversible. Once deleted, the webhook cannot be recovered.
\nEvents might be delivered shortly after the webhook is removed until the scheduled events are completely fan out.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}},"urlObject":{"path":["v1","webhooks",":id"],"host":["https://api.vat4u.com"],"query":[],"variable":[{"type":"any","value":"11","key":"id"}]}},"response":[],"_postman_id":"89c59f85-fb8a-445e-8cae-ee4373030736"}],"id":"1c1d3e05-3f6a-4da4-b2a7-d1748281b0c3","_postman_id":"1c1d3e05-3f6a-4da4-b2a7-d1748281b0c3","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{accessToken}}"}]},"isInherited":true,"source":{"_postman_id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","id":"4c1c61d8-d443-4144-8465-1a7d77deeb6d","name":"VAT4U API","type":"collection"}}},{"name":"Country","item":[{"name":"List countries","id":"70975024-8f1b-4d90-bb92-1a9a19ebf2de","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.vat4u.com/v1/countries","description":"Retrieves a list of countries supported by the API, including metadata such as country codes, EU membership status, and whether the country is currently in scope or out of scope of VAT4U.
\nA successful response returns HTTP 200 and a JSON array of country objects. Each object contains:
\nid (integer): Unique identifier for the country.
name (string): Full country name.
short_name (string): Short country name or abbreviation.
code (string): Country code (ISO).
eu_member (boolean): Indicates if the country is a member of the European Union.
in_scope (boolean): Indicates if the country is currently in scope of VAT4U.
[\n {\n \"id\": 1,\n \"name\": \"Belgium\",\n \"short_name\": \"BE\",\n \"code\": \"BE\",\n \"eu_member\": true,\n \"in_scope\": false\n },\n ...\n]\n\n