Viio Sync API
Last updated
The Viio Sync API is a customer-facing ingestion API for sending integration data to Viio. It is the same data path used by Viio-managed integrations.
Use the Sync API when:
- You need to control which data leaves a third-party product such as Microsoft Entra ID.
- Your source is custom, on-premises, or not supported by a Viio-managed integration.
- You need to transform, filter, or redact records inside your own environment before sending them.
- You want to own the extraction schedule while keeping the resulting data visible and actionable in Viio.
The Sync API complements the GraphQL API: use Sync API to write integration data into Viio, and GraphQL to read and work with Viio data.
How It Works
Each source reports data under a direct integration installation in your Viio workspace. The Sync API supports two processing models: snapshots for data that represents the source's current state, and events for activity that happened at a point in time.
Snapshot-backed data
Snapshot-backed data is a complete list of the records that currently exist in the source. Accounts, plans, licenses, employees, groups, group members, and devices use this model.
When you complete a batch for one of these datasets, Viio compares the stable source IDs received in the batch with the previous completed snapshot:
- New IDs are added.
- Existing IDs are updated.
- IDs that existed in the previous snapshot but are missing from the new snapshot are marked as removed.
This comparison lets Viio detect records deleted from the source even when the source only returns its current records and does not provide a deletion event.
For example, if a completed account snapshot contains account-1, account-2, and account-3, and the next completed account snapshot contains only account-1 and account-3, Viio treats account-2 as removed.
Event-based data
Usage, externally discovered usage, audit logs, AI usage, and AI cost are individual observations. Viio processes each accepted record as an event. The absence of an event from a later batch does not remove an earlier event.
Batch flow
- Start a batch using the direct integration installation ID.
- Stream snapshot-backed records, event records, or both in one or more messages.
- Complete the batch after every intended record has been accepted and every snapshot-backed collection included in the run is complete.
- Viio reconciles the included snapshot-backed collections, retains accepted events, and finishes the run.
Only one Sync API batch can be active for a direct integration installation at a time. A second run cannot start until the active batch is completed or aborted.
If a run cannot finish, abort it to release the integration lock and allow the next run to start. Aborting does not roll back records already accepted by Viio.
See the quickstart for the complete SDK lifecycle, including completion, deletion, abort, and retry behavior.
Endpoint
The production endpoint is:
https://sync.viio.io
The official SDKs connect to this endpoint over TLS with HTTP/2.
Supported Data
| Data type | Processing model | Common uses |
|---|---|---|
| Accounts | Snapshot | Accounts in a SaaS product, including identity, state, and roles |
| Plans and licenses | Snapshot | Subscription plans and the accounts assigned to them |
| Usage | Event | Last activity for an account, plan, or product |
| Employees | Snapshot | Workforce identity and organizational profile data |
| Groups and group members | Snapshot | Teams, directory groups, and membership relationships |
| Externally discovered usage | Event | Usage activity discovered by an external (non-Viio) Discovery Engine |
| Devices | Snapshot | Managed devices and their owners |
| Audit logs | Event | Application activity and its actor |
| AI usage and cost | Event | Provider-native AI consumption and cost records |
See the SDK Reference for the supported record models and their language-specific properties.
Before You Start
Currently, your Viio representative must provision a passive direct integration installation under which the source's data can be reported. Self-service creation of passive integrations in the Viio UI is coming soon.
You need:
- The direct integration installation ID.
- A workspace API key with write access and the
integration:syncpermission. - An official Viio Sync API SDK for your language when available.