Microsoft Excel Guide - Pinkfish - AI Agents & Workflows for Getting Work Done

What can you do with it?

Microsoft Excel integration allows you to programmatically manage spreadsheets and data through the Microsoft Graph API. You can create workbooks, search for Excel files, manage worksheets, read and write cell data, insert formulas, apply formatting, work with tables including adding, updating and deleting rows, and perform data operations like filtering and sorting. This integration is perfect for automated reporting, data processing workflows, spreadsheet management, converting CSV/JSON to Excel, and building data-driven applications that interact with Excel files stored in OneDrive for Business or SharePoint.

How to use it?

Basic Command Structure

/your-Microsoft-Excel-connection [action] [required-parameters] [optional-parameters]

Parameters

Required:

action - The operation to perform with Excel

Workbook Operations

Create Workbook

Create a new Excel workbook in OneDrive/SharePoint Parameters:

filename (required) - Name for the new workbook (e.g., “Sales Report.xlsx”)

Example:

/your-Microsoft-Excel-connection
action: create-workbook
filename: Sales Report 2024.xlsx

Response:

{
  "id": "01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR",
  "name": "Sales Report 2024.xlsx",
  "webUrl": "https://onedrive.live.com/...",
  "size": 8192,
  "createdDateTime": "2025-02-05T00:43:08Z"
}

Search Excel Files

Find Excel files by name to obtain workbook ID Parameters:

filename (required) - Name or partial name of the Excel file

Example:

/your-Microsoft-Excel-connection
action: search-file
filename: Sales Report

Response:

{
  "value": [
    {
      "name": "Sales Report 2024.xlsx",
      "id": "01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR",
      "lastModified": "2025-02-05T00:43:08Z",
      "webUrl": "https://onedrive.live.com/..."
    }
  ]
}

List Workbooks

Get all Excel workbooks from root or specific folder Parameters:

folder-id (optional) - Folder ID to search within (searches root if omitted)

Example:

/your-Microsoft-Excel-connection
action: list-workbooks

Response:

{
  "value": [
    {
      "id": "01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR",
      "name": "Sales Report 2024.xlsx",
      "size": 45678,
      "createdDateTime": "2025-01-15T10:30:00Z",
      "lastModifiedDateTime": "2025-02-05T00:43:08Z"
    }
  ]
}

Get Workbook Metadata

Get detailed information about a workbook Parameters:

workbook-id (required) - The ID of the Excel workbook

Example:

/your-Microsoft-Excel-connection
action: get-workbook-metadata
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR

Response:

{
  "id": "01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR",
  "name": "Sales Report 2024.xlsx",
  "createdDateTime": "2025-01-15T10:30:00Z",
  "lastModifiedDateTime": "2025-02-05T00:43:08Z",
  "size": 45678
}

Delete Workbook

Permanently delete an Excel workbook Parameters:

workbook-id (required) - The ID of the Excel workbook

Example:

/your-Microsoft-Excel-connection
action: delete-workbook
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR

Response:

{
  "status": "deleted"
}

Worksheet Operations

List Worksheets

Get all worksheets in a workbook Parameters:

workbook-id (required) - The ID of the Excel workbook

Example:

/your-Microsoft-Excel-connection
action: list-worksheets
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR

Response:

{
  "value": [
    {
      "id": "{00000000-0001-0000-0000-000000000000}",
      "name": "Sheet1",
      "position": 0,
      "visibility": "Visible"
    },
    {
      "id": "{00000000-0002-0000-0000-000000000000}",
      "name": "Summary",
      "position": 1,
      "visibility": "Visible"
    }
  ]
}

Create Worksheet

Add a new worksheet to a workbook Parameters:

workbook-id (required) - The ID of the Excel workbook
sheet-name (required) - Name for the new worksheet

Example:

/your-Microsoft-Excel-connection
action: create-worksheet
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
sheet-name: Q1 Data

Response:

{
  "id": "{75A18F35-34AA-4F44-97CC-FDC3C05D9F40}",
  "name": "Q1 Data",
  "position": 2,
  "visibility": "Visible"
}

Get Specific Worksheet

Get worksheet details by name or ID Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet

Example:

/your-Microsoft-Excel-connection
action: get-worksheet
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1

Response:

{
  "id": "{00000000-0001-0000-0000-000000000000}",
  "name": "Sheet1",
  "position": 0,
  "visibility": "Visible"
}

Rename Worksheet

Change worksheet name or position Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The current ID or name of the worksheet
new-name (optional) - New name for the worksheet
position (optional) - New position index

Example:

/your-Microsoft-Excel-connection
action: rename-worksheet
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
new-name: Sales Data
position: 0

Response:

{
  "id": "{00000000-0001-0000-0000-000000000000}",
  "name": "Sales Data",
  "position": 0,
  "visibility": "Visible"
}

Delete Worksheet

Remove a worksheet from a workbook Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet to delete

Example:

/your-Microsoft-Excel-connection
action: delete-worksheet
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Old Data

Response:

{
  "status": "deleted"
}

Data Operations

Read Data from Range

Read cell values from a worksheet Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (optional) - Cell range (e.g., A1:D10, A1). Omit to read entire used range

Example:

/your-Microsoft-Excel-connection
action: read-range
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: A1:D10

Response:

{
  "address": "Sheet1!A1:D10",
  "values": [
    ["Product", "Quantity", "Price", "Total"],
    ["Product A", 100, 25.99, 2599.00],
    ["Product B", 50, 35.99, 1799.50]
  ]
}

Write Data to Range

Write values to cells in a worksheet Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (required) - Starting cell address (e.g., A1)
values (required) - 2D array of values to write

Example:

/your-Microsoft-Excel-connection
action: write-range
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: A1
values: [["Product", "Quantity"], ["Product A", 100], ["Product B", 50]]

Response:

{
  "status": "success",
  "address": "Sheet1!A1:B3"
}

Write Formulas

Insert Excel formulas into cells Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (required) - Cell address for the formula
formula (required) - Formula string starting with ”=”

Example:

/your-Microsoft-Excel-connection
action: write-formula
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: D2
formula: =B2*C2

Response:

{
  "status": "success",
  "address": "Sheet1!D2",
  "formula": "=B2*C2"
}

Convert CSV/JSON to Excel

Create Excel files from CSV or JSON data Parameters:

filename (required) - Name for the new Excel file
data (required) - CSV string or JSON array to convert
data-type (required) - Either “csv” or “json”

Example:

/your-Microsoft-Excel-connection
action: convert-to-excel
filename: Data Export.xlsx
data-type: json
data: [{"Product": "A", "Quantity": 100}, {"Product": "B", "Quantity": 50}]

Response:

{
  "workbookId": "01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR",
  "name": "Data Export.xlsx",
  "webUrl": "https://onedrive.live.com/..."
}

Formatting Operations

Format Range - Font Styling

Apply font properties to cells Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (required) - Range to format (e.g., A1:D1)
bold (optional) - true/false
italic (optional) - true/false
size (optional) - Font size (e.g., 12)
color (optional) - Hex color code (e.g., “#FF0000”)
font-name (optional) - Font name (e.g., “Calibri”)

Example:

/your-Microsoft-Excel-connection
action: format-font
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: A1:D1
bold: true
size: 14
color: "#000000"

Response:

{
  "status": "success",
  "range": "A1:D1"
}

Format Range - Fill Color

Apply background color to cells Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (required) - Range to format
color (required) - Hex color code (e.g., “#4472C4”)

Example:

/your-Microsoft-Excel-connection
action: format-fill
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: A1:D1
color: "#4472C4"

Response:

{
  "status": "success",
  "range": "A1:D1"
}

Format Range - Borders

Add borders to cells Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (required) - Range to format
color (optional) - Hex color code (default: “#000000”)
style (optional) - Border style: “Continuous”, “Dash”, “DashDot”, “DashDotDot”, “Dot”, “Double”, “None”
weight (optional) - Border weight: “Thin”, “Medium”, “Thick”

Example:

/your-Microsoft-Excel-connection
action: format-borders
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: A1:D10
color: "#000000"
style: Continuous
weight: Thin

Response:

{
  "status": "success",
  "range": "A1:D10"
}

Format Range - Number Format

Apply number formatting to cells Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (required) - Range to format
number-format (required) - Format string (e.g., ”$#,##0.00” for currency, “0.00%” for percentage)

Example:

/your-Microsoft-Excel-connection
action: format-number
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: C2:C10
number-format: "$#,##0.00"

Response:

{
  "status": "success",
  "range": "C2:C10"
}

Common Number Formats:

Currency: $#,##0.00
Percentage: 0.00%
Date: mm/dd/yyyy
Time: h:mm:ss AM/PM
Accounting: _($* #,##0.00_);_($* (#,##0.00);_($* "-"??_);_(@_)
Custom: 0.000, #,##0, yyyy-mm-dd

Format Range - Alignment

Set text alignment in cells Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (required) - Range to format
horizontal-alignment (optional) - “Left”, “Center”, “Right”, “Justify”, “Distributed”
vertical-alignment (optional) - “Top”, “Middle”, “Bottom”, “Justify”, “Distributed”
wrap-text (optional) - true/false

Example:

/your-Microsoft-Excel-connection
action: format-alignment
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: A1:D1
horizontal-alignment: Center
vertical-alignment: Middle
wrap-text: true

Response:

{
  "status": "success",
  "range": "A1:D1"
}

Combined Format Update

Apply multiple format properties at once (more efficient than separate calls) Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
cell-range (required) - Range to format
Multiple formatting parameters from font, fill, number format, and alignment

Example:

/your-Microsoft-Excel-connection
action: format-combined
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
cell-range: A1:D1
bold: true
fill-color: "#4472C4"
horizontal-alignment: Center

Response:

{
  "status": "success",
  "range": "A1:D1"
}

Table Operations

Create Table

Convert a range to an Excel Table with headers Parameters:

workbook-id (required) - The ID of the Excel workbook
worksheet-id (required) - The ID or name of the worksheet
table-range (required) - Range for the table (e.g., A1:D10)
has-headers (optional) - Whether first row contains headers (default: true)

Example:

/your-Microsoft-Excel-connection
action: create-table
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
worksheet-id: Sheet1
table-range: A1:D10
has-headers: true

Response:

{
  "id": "Table1",
  "name": "Table1",
  "showHeaders": true,
  "showTotals": false,
  "style": "TableStyleMedium2"
}

Add Table Row

Insert a new row into an Excel Table Parameters:

workbook-id (required) - The ID of the Excel workbook
table-id (required) - The ID of the table
row-data (required) - Array of values for the new row

Example:

/your-Microsoft-Excel-connection
action: add-table-row
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
table-id: Table1
row-data: ["Product A", 100, 25.99, 2599.00]

Response:

{
  "index": 10,
  "values": [["Product A", 100, 25.99, 2599.00]]
}

Update Table Row

Modify an existing table row Parameters:

workbook-id (required) - The ID of the Excel workbook
table-id (required) - The ID of the table
row-index (required) - 0-based index within table (excluding header)
row-data (required) - Array of new values

Example:

/your-Microsoft-Excel-connection
action: update-table-row
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
table-id: Table1
row-index: 0
row-data: ["Product A Updated", 150, 29.99, 4498.50]

Response:

{
  "index": 0,
  "values": [["Product A Updated", 150, 29.99, 4498.50]]
}

Delete Table Row

Remove a row from a table Parameters:

workbook-id (required) - The ID of the Excel workbook
table-id (required) - The ID of the table
row-index (required) - 0-based index of row to delete

Example:

/your-Microsoft-Excel-connection
action: delete-table-row
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
table-id: Table1
row-index: 5

Response:

{
  "status": "deleted"
}

Get Table Data

Read all rows from a table Parameters:

workbook-id (required) - The ID of the Excel workbook
table-id (required) - The ID of the table

Example:

/your-Microsoft-Excel-connection
action: get-table-data
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
table-id: Table1

Response:

{
  "value": [
    {
      "index": 0,
      "values": [["Product A", 100, 25.99, 2599.00]]
    },
    {
      "index": 1,
      "values": [["Product B", 50, 35.99, 1799.50]]
    }
  ]
}

Filter Table Data

Apply filter criteria to table columns Parameters:

workbook-id (required) - The ID of the Excel workbook
table-id (required) - The ID of the table
column-id (required) - Column index or name to filter
filter-criteria (required) - Filter specification (varies by filter type)

Example:

/your-Microsoft-Excel-connection
action: filter-table
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
table-id: Table1
column-id: 1
filter-criteria: {"values": ["Product A", "Product C"]}

Response:

{
  "status": "success"
}

Sort Table Data

Sort table by one or more columns Parameters:

workbook-id (required) - The ID of the Excel workbook
table-id (required) - The ID of the table
sort-fields (required) - Array of sort specifications with key (column index) and ascending (true/false)

Example:

/your-Microsoft-Excel-connection
action: sort-table
workbook-id: 01HRDJMGPNAGXLOFE4URDYNKMBXOIES4BR
table-id: Table1
sort-fields: [{"key": 2, "ascending": false}]

Response:

{
  "status": "success"
}

Best Practices

Authorization: Requires Files.Read for read operations, Files.ReadWrite for write operations
Workbook ID: Always obtain workbook-id first using search or list operations
URL Encoding: Encode special characters in sheet names and worksheet IDs
Data Format: Ensure all rows in 2D arrays have same column count (pad with null if needed)
Formulas: Write formulas as strings starting with ”=”, they auto-calculate when written
Formatting: Apply formatting after writing data for better performance
Error Handling: Check for ItemNotFound (404) and AccessDenied (403) errors

Storage and File Support

Storage Support:

OneDrive for Business: ✓ Supported
SharePoint: ✓ Supported
OneDrive Consumer: ✗ Not supported

File Format Support:

.xlsx (Office Open XML): ✓ Supported
.xls: ✗ Not supported

Error Responses

Session Expired (404):

{
  "error": {
    "code": "ItemNotFound",
    "message": "Session not found."
  }
}

Invalid Permissions (403):

{
  "error": {
    "code": "AccessDenied",
    "message": "Insufficient permissions"
  }
}

Invalid Range (400):

{
  "error": {
    "code": "InvalidArgument",
    "message": "The argument is invalid or missing or has an incorrect format."
  }
}

Get Started

Organization

Agents

Workflows

Resources

Integrations

Orchestration

Credits & Pricing

Skills

How To Guides

Release Notes

Support

​What can you do with it?

​How to use it?

​Basic Command Structure

​Parameters

​Workbook Operations

​Create Workbook

​Search Excel Files

​List Workbooks

​Get Workbook Metadata

​Delete Workbook

​Worksheet Operations

​List Worksheets

​Create Worksheet

​Get Specific Worksheet

​Rename Worksheet

​Delete Worksheet

​Data Operations

​Read Data from Range

​Write Data to Range

​Write Formulas

​Convert CSV/JSON to Excel

​Formatting Operations

​Format Range - Font Styling

​Format Range - Fill Color

​Format Range - Borders

​Format Range - Number Format

​Format Range - Alignment

​Combined Format Update

​Table Operations

​Create Table

​Add Table Row

​Update Table Row

​Delete Table Row

​Get Table Data

​Filter Table Data

​Sort Table Data

​Best Practices

​Storage and File Support

​Error Responses

What can you do with it?

How to use it?

Basic Command Structure

Parameters

Workbook Operations

Create Workbook

Search Excel Files

List Workbooks

Get Workbook Metadata

Delete Workbook

Worksheet Operations

List Worksheets

Create Worksheet

Get Specific Worksheet

Rename Worksheet

Delete Worksheet

Data Operations

Read Data from Range

Write Data to Range

Write Formulas

Convert CSV/JSON to Excel

Formatting Operations

Format Range - Font Styling

Format Range - Fill Color

Format Range - Borders

Format Range - Number Format

Format Range - Alignment

Combined Format Update

Table Operations

Create Table

Add Table Row

Update Table Row

Delete Table Row

Get Table Data

Filter Table Data

Sort Table Data

Best Practices

Storage and File Support

Error Responses