Account, Opportunity, and Patient Identifiers for the Opportunity API
Overview
When creating Opportunities via POST /api/opportunity, understanding how Account, Opportunity, and Patient objects relate is essential to using the identifier fields correctly.
Object Hierarchy
Sunwave's data model is built around three objects:
Account: represents one physical person seeking treatment. There should only ever be one Account per person, regardless of how many times they seek treatment.
Opportunity: created each time that person seeks treatment. A single Account can have multiple Opportunities over time.
Patient: created from an Opportunity as that person is actually admitted.
All Patients and Opportunities for one person live under a single Account.
Legacy IDs
Sunwave assigns its own IDs to Accounts and Opportunities when they're created. Since integrations often need to address these objects using IDs from another system, Sunwave supports Legacy IDs for both Accounts and Opportunities. Legacy IDs are visible and editable in the UI.
Patients do not have a Legacy ID. The API is designed for funneling Opportunities in from an external CRM, not for reading live Patient data.
Identifier Fields on POST /api/opportunity
Either account_id or sunwave_account_id is required. opportunity_id is optional but recommended.
Field | Purpose |
|---|---|
| Your identifier from the originating system (e.g. Salesforce, Dazos). Pass this on every Opportunity creation call to prevent duplicate Account creation. If the Account already has an active Opportunity, the call will error. If the |
| The native Sunwave Account ID. Useful when Legacy IDs haven't been mapped yet but existing Sunwave Account IDs are already known. Only accepts existing Sunwave Account IDs. |
| Maps the created Opportunity to its ID in your CRM. Generally recommended. |
Common Scenario: Brand-New Prospect
For a prospect with no existing Sunwave presence, pass account_id using your own CRM identifier. This creates a new Account with that value as its Legacy ID, and Sunwave generates a new sunwave_account_id in response.
Viewing/Editing Account Legacy IDs in the UI
Viewing/Editing Opportunity Legacy IDs in the UI