Skip to Content
DestinationsOtherMicrosoft Excel

Microsoft Excel

Sync data to a Microsoft Excel workbook stored in OneDrive or SharePoint. Use Zeotap to push model results, audience lists, or enriched datasets directly into Excel spreadsheets for teams that work in Microsoft 365.

Prerequisites

  • A Microsoft 365 account (Business or Enterprise) with OneDrive or SharePoint access
  • An Excel workbook (.xlsx) stored in OneDrive or SharePoint — local files are not supported
  • The authenticated account must have read/write access to the workbook
  • If writing to a named table, the table must already exist in the workbook

Authentication

Microsoft Excel supports two authentication methods.

  1. Click Connect with OAuth in Zeotap
  2. Sign in with your Microsoft account
  3. Authorize Zeotap to access your OneDrive files
  4. Zeotap receives Files.ReadWrite and offline_access scopes

Bearer Token

  1. Obtain a Microsoft Graph API access token with Files.ReadWrite scope
  2. Enter the token in the Access Token field
  3. Note: Bearer tokens expire (typically after 1 hour) and must be refreshed manually

Configuration

FieldTypeRequiredDescription
Drive IDTextNoThe ID of the OneDrive or SharePoint document library. Leave blank to use the authenticated user’s default OneDrive.

Target Settings

FieldTypeRequiredDescription
Workbook Item IDTextNoThe unique ID of the Excel workbook file in OneDrive/SharePoint. Provide either Item ID or File Path.
Workbook File PathTextNoThe path to the Excel workbook (e.g., /Documents/data.xlsx). Provide either Item ID or File Path.
Table NameTextNoThe name of an existing Excel table to write data to. If not specified, data is written to the worksheet range directly.
Worksheet NameTextNoThe name of the worksheet tab. Used when writing to a range (no table specified). Default: Sheet1.

Supported Operations

Sync Modes

ModeSupportedDescription
InsertYesAppend new rows to the table or worksheet
MirrorYesClear all existing data, then write the complete dataset
Upsert—Not supported (Excel has no row-level key matching)
Update—Not supported (Excel has no row-level key matching)

Audience Sync Modes

ModeSupportedDescription
AddYesAppend audience members as new rows
MirrorYesReplace all rows with the current audience membership
Remove—Not supported
Upsert—Not supported

Features

  • Field Mapping: Yes — map source fields to specific Excel columns
  • Schema Introspection: Yes — Zeotap reads table column names or the first row of the worksheet as column headers

How It Works

Zeotap writes data to Excel workbooks via the Microsoft Graph API:

Table Mode

When a Table Name is specified, Zeotap writes rows to the named Excel table:

  1. Rows are added using the Graph API tables/{name}/rows endpoint
  2. Data is chunked into batches of 100 rows per API call
  3. Column ordering matches the table’s existing column structure
  4. For Mirror mode, the table’s data body is cleared before writing

Range Mode

When no table is specified, Zeotap writes to the worksheet as a range:

  1. The first row is written as column headers
  2. Data is written using the Graph API range update endpoint
  3. For Mirror mode, the worksheet’s used range is cleared before writing
  4. The range is calculated dynamically based on the number of columns and rows

Batch Processing

  • Table mode: rows are chunked into batches of 100 to stay within Graph API limits
  • Range mode: all rows are written in a single range update call
  • Failed chunks are tracked and reported in sync results

Rate Limits

Microsoft Graph API applies dynamic throttling to Excel workbook operations. There are no fixed numeric limits published — the API throttles based on resource consumption. When throttled, the API returns HTTP 429 with a Retry-After header.

Best practices to avoid throttling:

  • Avoid concurrent writes to the same workbook from multiple syncs
  • For very large datasets (10,000+ rows), consider using a warehouse destination instead
  • Schedule syncs during off-peak hours if possible

Best Practices

  • Use named tables for structured data — table mode provides better column alignment and data management
  • Use range mode for simple data dumps where exact column structure is not critical
  • Prefer OAuth over bearer tokens — OAuth tokens refresh automatically, while bearer tokens expire
  • Keep workbooks under 5 MB — very large workbooks may experience slower API response times
  • Use Item ID over File Path when possible — Item IDs are stable across file renames and moves

Troubleshooting

Workbook not found

Verify the Item ID or File Path is correct. The Item ID can be found in the OneDrive/SharePoint URL or via the Graph API Explorer. The file must be an .xlsx file — .xls and .csv files are not supported by the Graph API Excel endpoints.

Authentication expired

OAuth tokens refresh automatically. If you still see auth errors, reconnect the Microsoft Excel integration in Zeotap by re-authorizing with OAuth. For bearer tokens, generate a new token and update the destination credentials.

Permission denied

The authenticated Microsoft account must have Edit access to the workbook. View-only or read-only access is not sufficient. For SharePoint files, ensure the account has Contribute or Edit permissions on the document library.

Table not found

The specified table must already exist in the workbook. Create the table in Excel first: select your data range, then click Insert > Table. Name the table via the Table Design tab in Excel.

Rate limited (HTTP 429)

Microsoft Graph API is throttling requests. Zeotap respects the Retry-After header and retries automatically. If throttling persists, reduce sync frequency or split data across multiple workbooks.

Worksheet not found

Verify the worksheet name matches exactly (case-sensitive). The default is Sheet1. If you renamed the default worksheet in Excel, update the Worksheet Name in Zeotap to match.

Large dataset timeouts

The Microsoft Graph API has a request timeout for Excel operations. For datasets exceeding 10,000 rows, consider:

  • Using a named table (table mode handles chunking better)
  • Splitting data across multiple worksheets or workbooks
  • Using a warehouse destination (BigQuery, Snowflake) for very large datasets
Last updated on
UserflowCommon Room