Update Rows in Excel

PDF4me Update Rows is a REST endpoint that writes JSON data into existing rows of an Excel workbook. POST the .xlsx as Base64 to office/ApiV2Excel/ExcelUpdateRows with your data in jsonInput, target rows by Excel table name or by 1-based coordinates, then decode the updated workbook from the JSON response. Numeric and date conversion is automatic by default.

What this endpoint does

Takes a workbook plus a JSON array of objects and writes those values into existing rows: refreshed prices in a rate card, corrected records in a report, synced fields from your CRM. You choose where the data lands with one of two targeting modes, a named Excel table or exact row and column coordinates. The response is JSON with the updated workbook as Base64 content.

Authenticating Your API Request

Every PDF4me REST call must include your API key in the Authorization header as Basic auth. Get or rotate your key from the developer dashboard.

Get your API Key

Endpoint

POSToffice/ApiV2Excel/ExcelUpdateRows

Postman URLhttps://api.pdf4me.com/office/ApiV2Excel/ExcelUpdateRows

Important Facts You Should Not Miss

jsonInput is a string, not a JSON array

The update data travels as an escaped JSON string inside jsonInput. Sending a raw array there is the most common cause of a 400 on this endpoint. Serialize first, then embed.

Two targeting modes, chosen by tableName

A non-empty tableName switches to table mode with excelRowNumber; an empty one means coordinate mode with insertFromRow/insertFromColumn. All positions are 1-based.

The response is Base64 JSON, not the file

The updated workbook comes back as a Base64 string inside a JSON body with fileName, success, and errorMessage. Decode it before saving; the raw response is not a valid .xlsx.

HTTP setup

Method: POST
URL: https://api.pdf4me.com/office/ApiV2Excel/ExcelUpdateRows
Content-Type: application/json
Authorization: Basic <your PDF4me API key>

The response is JSON: check the success flag, then Base64-decode the returned workbook content and save it with an .xlsx extension.

Should I use table mode or coordinate mode?

The two modes serve different worksheet layouts, and picking the wrong one is the usual reason an update lands in the wrong cells.

Table mode vs coordinate mode	Table mode	Coordinate mode
How to select it	Set `tableName` to a named Excel table	Leave `tableName` empty
Where the data lands	Row `excelRowNumber` inside the table (1-based)	Starting at `insertFromRow`/`insertFromColumn` (1-based, so 1/1 is A1)
Column matching	JSON property names map to table column headers	Values written left to right from the start column
Survives layout changes	Yes, the update follows the table if it moves	No, coordinates are fixed positions
Best for	Structured worksheets with real Excel tables	Plain ranges and ad-hoc sheets

API body fields

Parameter	Required	Type	What it does	Example
`document`	Required	object	Document reference carrying Name, the Excel filename with its extension.	`{ "Name": "data.xlsx" }`
`docContent`	Required	string	Base64-encoded bytes of the workbook to update.	`UEsDBBQABgAIAAAA...`
`updateRowsToExcelAction`	Required	object	Action configuration object holding jsonInput and all targeting options below.	`{ "jsonInput": "..." }`
`jsonInput`	Required	string	Inside the action object. A STRING containing an escaped JSON array of objects; property names become column targets in table mode.	`"[{\"Name\":\"John\",\"Age\":31}]"`
`worksheetName`	Optional	string	Inside the action object. Target worksheet; defaults to the first sheet when omitted.	`Sheet1`
`tableName`	Conditional	string	Inside the action object. Names the Excel table for table mode. Empty or omitted switches the action to coordinate mode.	`SalesTable`
`excelRowNumber`	Conditional	number	Inside the action object. Table mode only: the 1-based row position within the table to update.	`5`
`insertFromRow`	Conditional	number	Inside the action object. Coordinate mode only: the 1-based worksheet row where writing starts.	`10`
`insertFromColumn`	Conditional	number	Inside the action object. Coordinate mode only: the 1-based worksheet column where writing starts.	`1`
`convertNumericAndDate`	Optional	boolean	Inside the action object. true (default) writes numeric-looking and date-looking values as real Excel numbers and dates instead of text.	`true`
`cultureName`	Optional	string	Inside the action object. Culture used to parse dates and numbers, for example en-US or de-DE. Pair with convertNumericAndDate.	`en-US`

Sample payloads

Table mode: update row 5 of a named table

{
 "document": { "Name": "sales.xlsx" },
 "docContent": "UEsDBBQABgAIAAAA...",
 "updateRowsToExcelAction": {
 "jsonInput": "[{\"Region\":\"EMEA\",\"Revenue\":125000}]",
 "worksheetName": "Q3",
 "tableName": "SalesTable",
 "excelRowNumber": 5
 }
}

Coordinate mode: write starting at cell A10

{
 "document": { "Name": "data.xlsx" },
 "docContent": "UEsDBBQABgAIAAAA...",
 "updateRowsToExcelAction": {
 "jsonInput": "[{\"Name\":\"John\",\"Age\":31},{\"Name\":\"Ana\",\"Age\":28}]",
 "insertFromRow": 10,
 "insertFromColumn": 1,
 "convertNumericAndDate": true,
 "cultureName": "en-US"
 }
}

Postman collection tips

Headers

Content-Type: application/json + Authorization: Basic <apiKey>.

Body

raw JSON. jsonInput must be a string: escape the inner quotes or use your HTTP library to serialize the array first, then assign it as a string.

Targeting

tableName set = table mode with excelRowNumber. tableName empty = coordinate mode with insertFromRow/insertFromColumn. Both are 1-based.

Response

JSON with a success flag and Base64 workbook content. Decode the document field before saving as .xlsx.

curl example

curl -X POST https://api.pdf4me.com/office/ApiV2Excel/ExcelUpdateRows \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "document": { "Name": "data.xlsx" },
 "docContent": "'"$(base64 -w 0 data.xlsx)"'",
 "updateRowsToExcelAction": {
 "jsonInput": "[{\"Name\":\"John\",\"Age\":31}]",
 "insertFromRow": 10,
 "insertFromColumn": 1
 }
 }' \
 --output response.json

What does the API return?

A JSON result carrying the updated workbook as Base64.

Field	Type	What it contains
`document`	String (Base64)	The updated workbook content. Decode to bytes and save with an .xlsx extension.
`fileName`	String	Output filename for the updated workbook.
`success`	Boolean	true when the update succeeded. Check this before decoding content.
`errorMessage`	String	Populated when success is false: malformed jsonInput, a missing table or worksheet, or invalid Base64.

The output stays a standard Office Open XML workbook, so formulas, formatting, and sheets outside the updated cells are untouched.

Code samples

Excel office endpoints are not yet covered by per-language sample folders; the samples repository carries the request pattern used by every PDF4me endpoint family:

View API Samples Repository

FAQ

Why does the API reject my jsonInput with a 400 error?+

jsonInput is a string field that contains JSON, so the inner quotes must be escaped. Sending a raw JSON array instead of a string-encoded one is the most common cause of a 400 Bad Request on this endpoint.

Should I use table mode or coordinate mode?+

Use table mode (tableName plus excelRowNumber) when the worksheet has a named Excel table: the update follows the table even if it moves. Use coordinate mode (insertFromRow and insertFromColumn, tableName empty) for plain ranges at fixed positions.

Are the row and column numbers 0-based or 1-based?+

1-based. insertFromRow 1 and insertFromColumn 1 address cell A1, and excelRowNumber 1 is the first data row of the table. This differs from some other PDF4me Excel actions where worksheet indexes are 0-based.

Is the response the Excel file itself?+

No. The API returns JSON containing the updated workbook as a Base64 string plus fileName, success, and errorMessage fields. Decode the document field to bytes before saving as .xlsx.

How are numbers and dates handled?+

convertNumericAndDate defaults to true, so values that look like numbers or dates are written as real Excel numbers and dates rather than text. Pair it with cultureName so formats like 31.12.2026 or 12/31/2026 parse correctly.

What is the difference between Update Rows and Add Rows?+

Update Rows overwrites values in rows that already exist at the targeted position. Add Rows appends or inserts new rows. If you point Update Rows at empty cells it simply writes the values there; it does not shift existing data down.

Can I update rows in a protected workbook?+

No. Protection blocks editing. Chain the Unlock Excel action first with the correct password, run the update, then re-apply protection with Secure Excel Document if needed.

Why update Excel rows via API instead of manually?

The manual route is opening each workbook, finding the rows, retyping the values, and saving: workable once, unworkable for a nightly sync from a CRM or database. The API makes the same edit as one deterministic request per file, keeps Excel tables intact, and never needs Excel installed on the server. The output is a standard Office Open XML workbook ready for the next step in the pipeline.

Add Rows

Append or insert new rows instead of overwriting existing ones.

Delete Rows

Remove obsolete rows before or after your update pass.

Extract Rows

Read rows out of the workbook to verify what your update wrote.