*REST API › Endpoint reference › Finance › Invoices* # Create or update the mirror of an externally issued invoice > Keeps in Filmo a read-only copy of an invoice issued by ANOTHER system (an ERP such as Business Central), so the operations team can see it. Filmo does not issue it: it is not numbered against a Filmo series, not signed and never sent to Verifactu. It is stored validated, locked and marked as externally issued, and in Filmo it cannot be edited, voided, collected, rectified, e-invoiced or emailed: every change arrives through this same call. The key is the pair in the path: repeating it updates the same mirror, and repeating the same content changes nothing. Responds 201 when it creates the mirror and 200 when it updates it or it was already identical. The customer is resolved by `contactId`, then by tax ID, then by exact name (contacts are never created implicitly); one that cannot be resolved is a 400 `validation_error` whose `errors[0].path` says why: `contactId` (no such contact), `contactTaxId` (several contacts share that tax ID, or none has it and no `contactName` was sent) or `contactName` (several contacts, or none, have that name). The declared totals are checked against the lines with a tolerance of one cent per line: if they do not match it is a 400 `validation_error` with `errors[0].path` `subTotal`, `taxTotal` or `total` (also `total` when base plus taxes do not add up to it); a tax rate that cannot be recognised for a line is `lines[n].taxRate`. 409 if the invoice number is already used by another invoice of the account, if the key belongs to an invoice that is not a synced mirror, or if a voided mirror is sent back as issued. Returns the full invoice, the same projection as its GET. `PUT /api/v1/invoices/external/{originSystem}/{originExternalId}` — scope `invoices:write` Scope: `invoices:write` · 120/min · Strict tenancy · Add-on (402) · Idempotency-Key · MCP: `filmo_invoices_upsert_external` ## Authorizations Bearer API key with the scope below. `invoices:write` ## Headers | Name | Type | Required | Description | | --- | --- | --- | --- | | `Idempotency-Key` | string | No | Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 `validation_error`, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the `Idempotent-Replay: true` header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout. | ## Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `originSystem` | string | Yes | Source system identifier, a lowercase slug (e.g. booqable, rentman, business_central). | | `originExternalId` | string | Yes | Identifier of the document in the source system. | ## Body Body schema: `InvoiceExternalUpsertBody` | Name | Type | Required | Description | | --- | --- | --- | --- | | `invoiceNumber` | string | Yes | Invoice number exactly as issued by the source system. | | `invoiceDate` | string | Yes | Issue date. | | `dueDate` | string | No | Due date. | | `currency` | string | No | ISO 4217 currency. = `"EUR"` | | `contactId` | string | No | Filmo contact identifier. | | `contactTaxId` | string | No | Customer tax ID, when its Filmo identifier is unknown. | | `contactName` | string | No | Exact customer name, as a last resort. | | `lines` | object[] | Yes | Invoice lines. | | `lines.description` | string | Yes | Line description. | | `lines.quantity` | string | Yes | Quantity. | | `lines.unitPrice` | string | Yes | Unit price before taxes. | | `lines.discountPercent` | string | No | Line discount as a percentage (0-100). | | `lines.taxType` | string | No | Filmo tax type (e.g. IVA_21). When missing it is inferred from taxRate. | | `lines.taxRate` | string | No | Tax percentage of the line (e.g. "21"). Required when taxType is missing. | | `subTotal` | string | No | Taxable base according to the source system (checked against the lines). | | `taxTotal` | string | No | Tax total according to the source system. | | `total` | string | No | Total according to the source system. | | `externalStatus` | string | No | issued, or voided in the source system. `issued`, `voided` = `"issued"` | | `voidReason` | string | No | Reason the source system voided it. | | `paymentStatus` | string | No | Payment status according to the source system. `unpaid`, `partially_paid`, `paid`, `overpaid` | | `totalPaid` | string | No | Amount collected according to the source system. | | `originUrl` | string | No | Link to the document in the source system (https). | | `originFileUrl` | string | No | Original PDF issued by the source system (https). | | `notes` | string | No | Internal notes. | ## Request examples *Create or update the mirror of an externally issued invoice* **cURL** ```bash curl https://app.filmo.io/api/v1/invoices/external/orig_8f2a1c/orig_8f2a1c \ --request PUT \ --header "Authorization: Bearer $FILMO_API_KEY" \ --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \ --header 'Content-Type: application/json' \ --data '{ "invoiceNumber": "FV26-001042", "invoiceDate": "2026-09-15", "dueDate": "2026-10-15", "currency": "EUR", "contactTaxId": "B00000000", "lines": [ { "description": "Alquiler de equipo de cámara (3 jornadas)", "quantity": "3", "unitPrice": "450.00", "taxRate": "21" }, { "description": "Transporte ida y vuelta", "quantity": "1", "unitPrice": "120.00", "taxType": "IVA_21" } ], "total": "1778.70", "externalStatus": "issued", "paymentStatus": "unpaid", "originUrl": "https://businesscentral.dynamics.com/?company=Filmo&page=132&filter=FV26-001042" }' ``` **Node.js** ```javascript fetch('https://app.filmo.io/api/v1/invoices/external/orig_8f2a1c/orig_8f2a1c', { method: 'PUT', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ invoiceNumber: 'FV26-001042', invoiceDate: '2026-09-15', dueDate: '2026-10-15', currency: 'EUR', contactTaxId: 'B00000000', lines: [ { description: 'Alquiler de equipo de cámara (3 jornadas)', quantity: '3', unitPrice: '450.00', taxRate: '21' }, { description: 'Transporte ida y vuelta', quantity: '1', unitPrice: '120.00', taxType: 'IVA_21' } ], total: '1778.70', externalStatus: 'issued', paymentStatus: 'unpaid', originUrl: 'https://businesscentral.dynamics.com/?company=Filmo&page=132&filter=FV26-001042' }) }) ``` **Python** ```python import uuid import requests requests.put( "https://app.filmo.io/api/v1/invoices/external/orig_8f2a1c/orig_8f2a1c", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "invoiceNumber": "FV26-001042", "invoiceDate": "2026-09-15", "dueDate": "2026-10-15", "currency": "EUR", "contactTaxId": "B00000000", "lines": [ { "description": "Alquiler de equipo de cámara (3 jornadas)", "quantity": "3", "unitPrice": "450.00", "taxRate": "21" }, { "description": "Transporte ida y vuelta", "quantity": "1", "unitPrice": "120.00", "taxType": "IVA_21" } ], "total": "1778.70", "externalStatus": "issued", "paymentStatus": "unpaid", "originUrl": "https://businesscentral.dynamics.com/?company=Filmo&page=132&filter=FV26-001042" } ) ``` ## Response Response schema: `InvoiceDetailDto` | Status | Description | | --- | --- | | 200 | Successful response. | | 201 | Created: the resource did not exist yet and was created. | | 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. | | 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). | | 402 | Add-on required (addon_required): the account plan does not include the add-on this operation needs; `requiredAddon` names it. | | 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. | | 404 | Resource not found (not_found): it does not exist or is outside the scope of the API key. | | 409 | Conflict (conflict): the current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. | | 422 | Idempotency-Key reused (idempotency_key_reused): the same key was used before with a different body. Change the key. | | 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. | | 500 | Internal error (internal_error). | **200** | Name | Type | Description | | --- | --- | --- | | `data` | object | The invoice in full, as returned by the API. | | `data.id` | string | Unique invoice identifier. | | `data.invoiceNumber` | string | Invoice number; null while it is a draft (the number is assigned on validation). | | `data.status` | string | Document lifecycle status: draft, validated (validated and numbered) or voided. `draft`, `validated`, `voided` | | `data.isRectification` | boolean | Whether the invoice rectifies a previous one. Invoices created in Filmo are never rectifications, and credit notes are served by `/api/v1/credit-notes`; but `/api/v1/invoices` can still return imported rectifying documents (for example from a Rentman import) with this set to true, so deduplicate them against the credit notes by number. | | `data.invoiceDate` | string | Issue date in ISO 8601 with offset; null while it is a draft. | | `data.dueDate` | string | Due date in ISO 8601 with offset; null if not set. | | `data.currency` | string | Invoice currency as an ISO 4217 code (for example "EUR"). | | `data.contact` | object | Compact reference to the invoiced contact; null if none. | | `data.contact.id` | string | Unique contact identifier. | | `data.contact.name` | string | Contact name. | | `data.orderId` | string | Identifier of the source order; null if the invoice does not come from an order. | | `data.orderNumber` | string | Number of the source order; null if the invoice does not come from an order. | | `data.projectId` | string | Identifier of the linked project; null if not linked. | | `data.subTotal` | string | Subtotal before discounts and taxes, as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.discountTotal` | string | Total discounts as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.taxesPrice` | string | Tax total as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.netPrice` | string | Taxable base (net before taxes) as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.grossPrice` | string | Total including taxes, as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.totalPaid` | string | Amount collected to date as a decimal string "1234.50" (ROUND_HALF_UP); null if not recorded. | | `data.paymentStatus` | string | Payment status: unpaid (nothing collected yet, also for invoices without a recorded collection), partially_paid, paid, overpaid (collected above the total), overdue (past due and unpaid) or voided (the document is voided, whatever was collected before). The `paymentStatus` filter uses the same values. `unpaid`, `partially_paid`, `paid`, `overpaid`, `overdue`, `voided` | | `data.paymentMethod` | string | Payment method of the invoice; null if not recorded. | | `data.tags` | object[] | Tags attached to the invoice, with their identifier and name. | | `data.tags.id` | string | Unique identifier of the tag. | | `data.tags.name` | string | Tag name. | | `data.createdAt` | string | Creation date in ISO 8601 with offset. | | `data.updatedAt` | string | Last update date in ISO 8601 with offset. | | `data.projectName` | string | Name of the linked project; null if not linked. | | `data.taxBreakdown` | object[] | Tax breakdown by type; null if not calculated. | | `data.taxBreakdown.taxType` | string | Tax type key (for example "IVA_21"). | | `data.taxBreakdown.label` | string | Human-readable tax label. | | `data.taxBreakdown.rate` | number | Tax rate applied, as a percentage (for example 21 for 21%). | | `data.taxBreakdown.baseAmount` | string | Taxable base the tax is applied to, as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.taxBreakdown.amount` | string | Tax amount as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.productDiscountTotal` | string | Total discounts applied at product level, as a decimal string "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. | | `data.globalDiscountTotal` | string | Global discount total of the document, as a decimal string "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. | | `data.insuranceTotal` | string | Insurance total as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.depositTotal` | string | Deposit total as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.exchangeRate` | number | Exchange rate applied when the currency differs from the base currency; null if not applicable. | | `data.billingAddress` | object | Billing address; null if not recorded. | | `data.billingAddress.label` | string | Descriptive label of the address; null if not recorded. | | `data.billingAddress.addressLine1` | string | First address line; null if not recorded. | | `data.billingAddress.addressLine2` | string | Second address line; null if not recorded. | | `data.billingAddress.city` | string | City; null if not recorded. | | `data.billingAddress.province` | string | Province or region; null if not recorded. | | `data.billingAddress.postcode` | string | Postal code; null if not recorded. | | `data.billingAddress.country` | string | Country; null if not recorded. | | `data.sourceQuoteIds` | string[] | Identifiers of the source quotes; null if the invoice does not come from quotes. | | `data.sourceProformaIds` | string[] | Identifiers of the source proformas; null if the invoice does not come from proformas. | | `meta` | object | Additional information about the response. | | `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. | | `meta.warnings.code` | string | Stable warning code. `deprecated` | | `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. | | `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. | | `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. | | `meta.warnings.link` | string | Where the deprecation is documented (the changelog). | *Example response · 200* ```json { "data": { "id": "invoice_9f3a2b", "invoiceNumber": "2026-0001", "status": "draft", "isRectification": true, "invoiceDate": "2026-09-01T08:00:00.000Z", "dueDate": "2026-09-01T08:00:00.000Z", "currency": "EUR", "contact": { "id": "contact_9f3a2b", "name": "Example contact" }, "orderId": "order_9f3a2b", "orderNumber": "2026-0001", "projectId": "project_9f3a2b", "subTotal": "120.00", "discountTotal": "120.00", "taxesPrice": "120.00", "netPrice": "120.00", "grossPrice": "120.00", "totalPaid": "120.00", "paymentStatus": "unpaid", "paymentMethod": "Example payment method", "tags": [ { "id": "tag_9f3a2b", "name": "Example tag" } ], "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-09-01T08:00:00.000Z", "projectName": "Example project name", "taxBreakdown": [ { "taxType": "120.00", "label": "Main", "rate": 1, "baseAmount": "120.00", "amount": "120.00" } ], "productDiscountTotal": "120.00", "globalDiscountTotal": "120.00", "insuranceTotal": "120.00", "depositTotal": "120.00", "exchangeRate": 1, "billingAddress": { "label": "Main", "addressLine1": "Calle de Ejemplo 12", "addressLine2": "Calle de Ejemplo 12", "city": "Madrid", "province": "Madrid", "postcode": "28001", "country": "ES" }, "sourceQuoteIds": [ "source_quote_9f3a2b" ], "sourceProformaIds": [ "source_proforma_9f3a2b" ] } } ``` **201** | Name | Type | Description | | --- | --- | --- | | `data` | object | The invoice in full, as returned by the API. | | `data.id` | string | Unique invoice identifier. | | `data.invoiceNumber` | string | Invoice number; null while it is a draft (the number is assigned on validation). | | `data.status` | string | Document lifecycle status: draft, validated (validated and numbered) or voided. `draft`, `validated`, `voided` | | `data.isRectification` | boolean | Whether the invoice rectifies a previous one. Invoices created in Filmo are never rectifications, and credit notes are served by `/api/v1/credit-notes`; but `/api/v1/invoices` can still return imported rectifying documents (for example from a Rentman import) with this set to true, so deduplicate them against the credit notes by number. | | `data.invoiceDate` | string | Issue date in ISO 8601 with offset; null while it is a draft. | | `data.dueDate` | string | Due date in ISO 8601 with offset; null if not set. | | `data.currency` | string | Invoice currency as an ISO 4217 code (for example "EUR"). | | `data.contact` | object | Compact reference to the invoiced contact; null if none. | | `data.contact.id` | string | Unique contact identifier. | | `data.contact.name` | string | Contact name. | | `data.orderId` | string | Identifier of the source order; null if the invoice does not come from an order. | | `data.orderNumber` | string | Number of the source order; null if the invoice does not come from an order. | | `data.projectId` | string | Identifier of the linked project; null if not linked. | | `data.subTotal` | string | Subtotal before discounts and taxes, as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.discountTotal` | string | Total discounts as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.taxesPrice` | string | Tax total as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.netPrice` | string | Taxable base (net before taxes) as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.grossPrice` | string | Total including taxes, as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.totalPaid` | string | Amount collected to date as a decimal string "1234.50" (ROUND_HALF_UP); null if not recorded. | | `data.paymentStatus` | string | Payment status: unpaid (nothing collected yet, also for invoices without a recorded collection), partially_paid, paid, overpaid (collected above the total), overdue (past due and unpaid) or voided (the document is voided, whatever was collected before). The `paymentStatus` filter uses the same values. `unpaid`, `partially_paid`, `paid`, `overpaid`, `overdue`, `voided` | | `data.paymentMethod` | string | Payment method of the invoice; null if not recorded. | | `data.tags` | object[] | Tags attached to the invoice, with their identifier and name. | | `data.tags.id` | string | Unique identifier of the tag. | | `data.tags.name` | string | Tag name. | | `data.createdAt` | string | Creation date in ISO 8601 with offset. | | `data.updatedAt` | string | Last update date in ISO 8601 with offset. | | `data.projectName` | string | Name of the linked project; null if not linked. | | `data.taxBreakdown` | object[] | Tax breakdown by type; null if not calculated. | | `data.taxBreakdown.taxType` | string | Tax type key (for example "IVA_21"). | | `data.taxBreakdown.label` | string | Human-readable tax label. | | `data.taxBreakdown.rate` | number | Tax rate applied, as a percentage (for example 21 for 21%). | | `data.taxBreakdown.baseAmount` | string | Taxable base the tax is applied to, as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.taxBreakdown.amount` | string | Tax amount as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.productDiscountTotal` | string | Total discounts applied at product level, as a decimal string "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. | | `data.globalDiscountTotal` | string | Global discount total of the document, as a decimal string "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. | | `data.insuranceTotal` | string | Insurance total as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.depositTotal` | string | Deposit total as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.exchangeRate` | number | Exchange rate applied when the currency differs from the base currency; null if not applicable. | | `data.billingAddress` | object | Billing address; null if not recorded. | | `data.billingAddress.label` | string | Descriptive label of the address; null if not recorded. | | `data.billingAddress.addressLine1` | string | First address line; null if not recorded. | | `data.billingAddress.addressLine2` | string | Second address line; null if not recorded. | | `data.billingAddress.city` | string | City; null if not recorded. | | `data.billingAddress.province` | string | Province or region; null if not recorded. | | `data.billingAddress.postcode` | string | Postal code; null if not recorded. | | `data.billingAddress.country` | string | Country; null if not recorded. | | `data.sourceQuoteIds` | string[] | Identifiers of the source quotes; null if the invoice does not come from quotes. | | `data.sourceProformaIds` | string[] | Identifiers of the source proformas; null if the invoice does not come from proformas. | | `meta` | object | Additional information about the response. | | `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. | | `meta.warnings.code` | string | Stable warning code. `deprecated` | | `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. | | `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. | | `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. | | `meta.warnings.link` | string | Where the deprecation is documented (the changelog). | *Example response · 201* ```json { "data": { "id": "invoice_9f3a2b", "invoiceNumber": "2026-0001", "status": "draft", "isRectification": true, "invoiceDate": "2026-09-01T08:00:00.000Z", "dueDate": "2026-09-01T08:00:00.000Z", "currency": "EUR", "contact": { "id": "contact_9f3a2b", "name": "Example contact" }, "orderId": "order_9f3a2b", "orderNumber": "2026-0001", "projectId": "project_9f3a2b", "subTotal": "120.00", "discountTotal": "120.00", "taxesPrice": "120.00", "netPrice": "120.00", "grossPrice": "120.00", "totalPaid": "120.00", "paymentStatus": "unpaid", "paymentMethod": "Example payment method", "tags": [ { "id": "tag_9f3a2b", "name": "Example tag" } ], "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-09-01T08:00:00.000Z", "projectName": "Example project name", "taxBreakdown": [ { "taxType": "120.00", "label": "Main", "rate": 1, "baseAmount": "120.00", "amount": "120.00" } ], "productDiscountTotal": "120.00", "globalDiscountTotal": "120.00", "insuranceTotal": "120.00", "depositTotal": "120.00", "exchangeRate": 1, "billingAddress": { "label": "Main", "addressLine1": "Calle de Ejemplo 12", "addressLine2": "Calle de Ejemplo 12", "city": "Madrid", "province": "Madrid", "postcode": "28001", "country": "ES" }, "sourceQuoteIds": [ "source_quote_9f3a2b" ], "sourceProformaIds": [ "source_proforma_9f3a2b" ] } } ``` ## Errors | Status | Codes | Meaning | | --- | --- | --- | | 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. | | 402 | `addon_required` | The account plan does not include the add-on this operation needs; `requiredAddon` names it. | | 404 | `not_found` | It does not exist or is outside the scope of the API key. | | 409 | `conflict` | The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. | | 422 | `idempotency_key_reused` | The same key was used before with a different body. Change the key. | ## Deprecation This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. --- Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/invoices/create-or-update-the-mirror-of-an-externally-issued-invoice Last updated: 2026-10-25