Data Sync

Data Sync keeps a Vizzlo document’s data in sync with an external spreadsheet. A sync job is attached to a single document and periodically re-downloads a spreadsheet from a remote source (a public URL, a shared spreadsheet link, or a file in a connected cloud storage account) and feeds its data into the document.

A connection is a stored link between a Vizzlo user and a cloud storage account (Box, Dropbox, Google Drive, OneDrive, Smartsheet), used to reach private files. See also Cloud Storage.

The typical flow is:

Check a source URL and inspect the available worksheets (/sync/document/check).
Optionally read the raw data of the source (/sync/document).
Create a sync job for a document (/sync/create).
Later, read or delete the sync job (/sync/document/:document).

Requests that fetch data from a remote provider have a 45-second deadline. If the provider does not respond in time, HTTP status code 504 Gateway Timeout is returned.

Checking a data source

Validates a remote source URL and returns metadata about it (the detected provider and the available worksheets), without persisting anything.

Route

POST /api/v1/sync/document/check

Request payload

{
  "url": "https://example.com/data.xlsx"
}

Return value

Name	Type	Description
`valid`	boolean	Whether the source could be read.
`provider_name`	string	The detected provider (e.g. `url`, `google-sheets`, `dropbox`, `box`, `onedrive`, `smartsheet`, …).
`source_error`	object	Optional: `{ "code": number, "message": string }` describing why the source could not be read.
`worksheets`	array	Optional: List of `{ "id": string, "name": string }` objects, one per worksheet.
`fixed_headers`	boolean	Optional: Whether the source uses fixed headers.
`static_worksheet`	boolean	Optional: Whether the source has a single, static worksheet.

Reading data from a source

Downloads and returns the actual spreadsheet data of a source URL — either one named worksheet or the whole workbook.

Route

POST /api/v1/sync/document

Request payload

{
  "url": "https://example.com/data.xlsx",
  "worksheet_name": "Sheet1",
  "worksheet_id": ""
}

If worksheet_name or worksheet_id is given, only that single worksheet is returned; otherwise the full workbook is returned.

Return value

When a single worksheet is requested, a worksheet object is returned:

{
  "name": "Sheet1",
  "sheet_id": "0",
  "rows": [
    ["Label", "Value"],
    ["Q1", 12]
  ]
}

When the full workbook is requested, a JSON array of such worksheet objects is returned. Cells are serialized as strings or numbers; date cells are returned as objects with type, display_value, date_string, and formatting_string.

Creating a sync job

Creates (or replaces) the sync job for a document. If the document already has a sync job, it is replaced. Requires write access to the document.

Route

POST /api/v1/sync/create

Request payload

Name	Type	Description
`document_id`	string	Required: UUID of the Vizzlo document to attach the sync job to.
`url`	string	Required: The remote source URL to sync from.
`document_settings`	object	Optional: Vizzard-specific settings applied to the document when syncing.
`sheet_name`	string	Optional: Name of the worksheet to sync.
`sheet_id`	string	Optional: ID of the worksheet to sync.
`interval_sec`	number	Sync interval in seconds.
`time_of_day_utc`	string	Time of day to sync (`HH:MM`, UTC). Required when `interval_sec` is greater than `0`.
`day_of_week`	number	Day of the week to sync (Sunday is `0`).

Return value

No content (HTTP status code 204) upon success.

Reading a sync job

Returns the sync job configuration and last download state for a document. Requires write access to the document.

Route

GET /api/v1/sync/document/document

Query parameters

fresh (boolean): Optional: If set, forces a fresh sync before returning.

Return value

Name	Type	Description
`document_settings`	object	Vizzard-specific settings applied when syncing.
`url`	string	The remote source URL.
`sheet_name`	string	Name of the synced worksheet.
`sheet_id`	string	ID of the synced worksheet.
`interval_sec`	number	Sync interval in seconds.
`time_of_day_utc`	string	Time of day the sync runs (`HH:MM`, UTC).
`day_of_week`	number	Day of the week the sync runs (Sunday is `0`).
`prepared_data`	object	Optional: The most recently prepared data.
`downloaded_at`	string	Optional: Timestamp (RFC 3339) of the last successful download.
`next_download_at`	string	Optional: Timestamp (RFC 3339) of the next scheduled download.
`error`	string	Optional: The last download error, if any.

If the document has no sync job, HTTP status code 404 is returned.

Deleting a sync job

Removes the sync job attached to a document. Requires write access to the document.

Route

DELETE /api/v1/sync/document/document

Return value

No content (HTTP status code 204) upon success.

Listing sync providers

Lists all supported cloud storage providers together with the current user’s access level and existing connections for each.

Route

GET /api/v1/sync/providers

Return value

A JSON array of provider objects:

Name	Type	Description
`name`	string	Provider identifier: `box`, `dropbox`, `googledrive`, `onedrive`, or `smartsheet`.
`description`	string	Human-readable provider name (e.g. “Google Drive”).
`access`	string	The user’s access level for this provider: `none`, `partial`, or `full`.
`auth_url`	string	Optional: URL to start the OAuth flow to connect this provider.
`connections`	array	Optional: The user’s existing connections for this provider (see below).

Listing sync connections

Lists the current user’s stored cloud storage connections as a flat list.

Route

GET /api/v1/sync/connections

Return value

A JSON array of connection objects:

Name	Type	Description
`id`	string	Connection ID, used to identify the connection in other API calls.
`provider`	string	The cloud storage provider of this connection.
`title`	string	User-visible title of the connection.
`email_address`	string	Email address used at the cloud storage provider.
`scopes`	string	Optional: OAuth scopes granted for this connection.
`urls`	object	Optional: Related URLs for this connection.

Access tokens are never included in the response.

Deleting a sync connection

Removes one of the current user’s cloud storage connections.

Route

DELETE /api/v1/sync/connections/connectionId

Return value

No content (HTTP status code 204) upon success. If the connection does not exist or does not belong to the current user, HTTP status code 404 is returned.