Allowed Scopes: experimental:external-reference:write

Records the ID a Spendesk entity has in an external system (ERP), namespaced by provider.
Re-sending the same (entityType, provider, externalId) updates the existing record.

Recording an external ID for an exportable entity (payable, settlementAllocation,
walletLoad, bankFee, documentaryEvidenceAttachment, creditNoteAllocation) also records that
entity as exported to the given provider, and it will then appear under
GET /v1/experimental/integrations/export-status?status=exported. Use it when you have
genuinely exported the entity to your own system. For reference entities (supplier,
employee, analyticalField, analyticalFieldValue, costCenter, expenseCategory,
customField) the write only stores the mapping and has no export side effect.

For the account kinds the external ID is set on the account itself, so entityId is the
account id — never the id of the supplier or employee an account of that type points at — and
provider, externalName and componentId are ignored, since an account row has nowhere
to keep them. provider is still required because the other kinds need it; send any non-empty
value. The account kinds are bankAccount, expenseAccount, taxAccount,
supplierAccount, employeeAccount and reverseChargeAccount; each asserts the target
account's own type, and the write is refused if it disagrees rather than applied to the wrong
account. There is no unqualified spelling, since an account's type is part of what identifies
it. An external ID must identify a
single account, so a write is also refused when another active account of the same type and
purpose already holds the value, and when a second reference in the same request gives one
account a different external ID.

Companies whose ERP is connected through a native integration cannot set external IDs at all:
Spendesk talks to that ERP directly and owns the mappings end to end. For accounts that is what
keeps the chart of accounts safe — it is synced from the ERP, and externalId is the ERP's own
key, so an API value there would be overwritten by the next sync.

Two exportable cases behave differently. While a native integration is mid-export for the
entity the write is refused: that integration owns the export it is running and records its own
external ID when the ERP answers. While a file-based export is mid-flight the external ID is
stored but the export state is left untouched, since that export is not ours to complete.

A native integration always takes precedence, and an API write never overwrites a value it owns.
For a reference entity the write is refused when a native sync already records an external ID for
that entity under the same provider, or when the external ID itself already belongs to a
natively synced entity — a different provider is still accepted, since references are
namespaced per ERP. For an exportable entity the write is refused whenever a native external ID
is already recorded, whatever provider you send, because there is a single external ID per
entity and component. Values you recorded through this API can be corrected freely.

Purchase orders are not accepted: externalPONumber is set on the purchase order itself at
creation time, so a second copy here would compete with it.

Each reference gets its own outcome, in request order — exported when the entity is now
recorded as exported, recorded when the external ID was stored but the export state was left
alone, mapped for a reference-entity or account write, and failed with a reason
otherwise. A batch may
mix entity kinds, so it can partially succeed: check every entry rather than the status code alone.