Copy Markdown

Two related but distinct mechanisms: Idempotency-Key prevents accidental duplicate requests on retry (one stable key per business action; same key

• same body replays the original response, same key + different body is a 409 IDEMPOTENCY_CONFLICT; see Errors). External References (externalReferences on create calls, plus /external-references/* endpoints, defined in apps/web/src/lib/org-api/openapi-contracts.ts) are how you reconcile solarOS records against IDs from another system across separate calls. Migrate from another CRM already shows both used together end to end.

TODO(owner, likely integrations): write the standalone reference page. This content currently only exists woven into the migration guide. Pull the externalReferences shape and the /external-references/* endpoint contracts from apps/web/src/lib/org-api/openapi-contracts.ts and give each mechanism its own worked example, independent of the HubSpot narrative.