Tenant and source scoped external IDs
External IDs are scoped by tenant and source system. The same external ID can exist in different tenants without being shared.
Customer Mapping boundaries
External IDs are safer than free-text matching because they preserve a deterministic relationship between source systems and Ordinavo customer records.
Customer-aware imports
Ordinavo Connect can receive customer, location and contact data from external systems and map imported jobs to the right customer context.
Mapping warnings
Mapping warnings are used when an automatic match is unsafe or ambiguous instead of silently linking to the wrong customer.
Controlled create/update behavior
Auto-create and update behavior depends on integration settings, feature gates and customer-related scopes.
CustomerNumber belongs to the Ordinavo customer record. It is not a separate operational target identifier.
API keys and scopes
Integration clients should use the smallest scope set needed for their workflow. Customer mapping and auto-create behavior require explicit customer-related scopes.
| Scope | Purpose |
|---|---|
targets.write |
Required to import targets. |
customers.map |
Required to link incoming records to existing Ordinavo customer references. |
customers.write |
Required for auto-create or auto-update behavior. |
customers.read |
Required to receive detailed mapping objects and customer mapping results. |
Security notes for integrations
- API keys should be treated as secrets.
- Scopes limit what an integration client can do.
- Customer mapping and auto-create require explicit customer-related scopes.
- Consumers should verify webhook signatures before processing events.
- Webhook receivers should store only the data they need.
Import transparency
Import jobs and import items can store mapping status, warnings and errors so operations and partner teams can understand what happened without broad internal access.
| Area | Description |
|---|---|
| Import jobs | Store accepted, processing, failed or completed state for batches and single imports. |
| Import items | Keep per-item status, external IDs, validation errors and mapping diagnostics. |
| Mapping status | Shows whether customer, location or contact context was mapped, created, updated, skipped or failed. |
| Mapping warnings | Expose non-fatal issues such as ambiguous matches, missing coordinates or disabled auto-create policies. |
| Webhook deliveries | Record delivery attempts, response codes and technical metadata for operational transparency. |
CustomerContext in outbound events
When a mapped job results in visit report, follow-up or billing trigger events, webhook payloads can include CustomerContext so external systems can connect Ordinavo events back to their own customer, site and contact records.
Contact details, summary previews and billing details should only be enabled for endpoints that need them.
Billing trigger events are structured signals
Ordinavo can mark approved, billable visit reports as billing trigger events. These events are designed to notify external ERP, accounting or billing systems that a completed visit may be relevant for downstream billing.
Ordinavo does not create invoices in this workflow. Billing details in webhook payloads should only be enabled for endpoints that need them.
Make imports testable and understandable
External developers should be able to import a customer-aware job, inspect the mapping result, request a route suggestion and receive signed webhook events.