# The Integration Id

A generic external-key field stamped onto the covered master and document tables so you can store and look up records by the external system's own key.

The JSON column is `integrationId`. It maps to a `Text[100]` field on the Business Central table and is backed by an index, so filtering is efficient:

```
GET eOne/core/v1.0/customers?$filter=integrationId eq 'SHOPIFY-1001'
```

## How it behaves

- Writable on masters, documents and lines. Set it on `POST` or `PATCH` to bind a Business Central record to your external key.
- Read-only on feeds and posted documents. The value is carried forward from the source document at posting time.
- It is independent of the Business Central primary key, so renaming a customer/item does not change its `integrationId`.
- Available to your own extensions. A companion API page over the same table can expose the same `integrationId`, so your fields line up with the eOne records. See [Extending the endpoints](https://eonesolutions.github.io/eone-bc-integration/extending.md).

> **Tip:** Already keeping the external key in a field of your own? Seed it into the Integration Id in bulk with the [migration tool](https://eonesolutions.github.io/eone-bc-integration/integration-id-migration.md) instead of re-keying every record.

## Sending the same key twice

A retried POST is the normal response to a timeout, and a timeout tells you nothing about whether Business Central accepted the document. So SmartConnect is rejected when it sends an `integrationId` that has already been used, rather than being allowed to create a second document. Two settings on the **eOne Integration Setup** page control this, both on by default:

- **Reject Duplicate Integration Ids.** Covers the ledger and expense endpoints. It rejects an `integrationId` that already belongs to a staged or processed document. See [Processed Documents](https://eonesolutions.github.io/eone-bc-integration/core-processedDocuments.md).
- **Reject Duplicate Documents.** Covers the writable sales and purchase document endpoints. It rejects an `integrationId` that is already on an open document of the same type, or on a document that type has been posted into.

The error names the document it collided with, so you can go straight to it. A rejected sales invoice reads `has already been posted as Sales Invoice 103021 on 14/08/26`.

## What counts as a duplicate document

The check looks at one pipeline at a time, and the pipeline is decided by the endpoint you posted to:

| POST to | Rejected when the `integrationId` is already on |
| --- | --- |
| `salesOrders` | an open sales order, a posted sales shipment, or a posted sales invoice |
| `salesInvoices` | an open sales invoice or a posted sales invoice |
| `salesCreditMemos` | an open sales credit memo or a posted sales credit memo |
| `salesReturnOrders` | an open sales return order, a posted return receipt, or a posted sales credit memo |
| `salesQuotes`, `salesBlanketOrders` | an open document of that type |
| `purchaseOrders` | an open purchase order, a posted purchase receipt, or a posted purchase invoice |
| `purchaseInvoices` | an open purchase invoice or a posted purchase invoice |
| `purchaseCreditMemos` | an open purchase credit memo or a posted purchase credit memo |
| `purchaseReturnOrders` | an open purchase return order, a posted return shipment, or a posted purchase credit memo |
| `purchaseQuotes`, `purchaseBlanketOrders` | an open document of that type |

Nothing outside that row blocks you. An order that ships and invoices leaves its `integrationId` on the posted invoice, so a standalone invoice sent later under the same key belongs to a different pipeline and goes through. Quotes and blanket orders never post, so only their own open documents are checked.

Archived and cancelled documents never block. The `cancel` action archives a document and then deletes it, so a cancelled order can be sent again under the same `integrationId`. See [Archiving & cancelling](https://eonesolutions.github.io/eone-bc-integration/archive.md).

Only creates are checked. Updating a document by its `integrationId` is the normal way these endpoints are used, so a PATCH is never rejected as a duplicate.