Why is this endpoint not under /api/v2/?

Excel operations belong to the PDF4me office API family, addressed as office/ApiV2Excel/ plus the action name on the same api.pdf4me.com host, with the same Basic Authorization header.

Unlock Excel

PDF4me Unlock Excel is a REST endpoint that removes password protection from an Excel workbook when you supply the correct password. POST the protected file as Base64 to office/ApiV2Excel/ExcelUnlock, put the password inside unlockExcelAction, and save the decoded unprotected copy from the JSON response. It removes protection; it never cracks it.

What this endpoint does

Takes a protected workbook plus its password and returns an unprotected copy. File encryption, workbook structure protection, and worksheet locks are all removed in one pass, which is what automated pipelines need before they can read cells, add rows, or merge files: every other Excel action expects an unprotected workbook. The response is JSON with the result 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/ExcelUnlock

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

Important Facts You Should Not Miss

Requires the correct password. Not a cracker

The API removes protection when you supply the password that was used to apply it. It cannot bypass, recover, or brute-force an unknown password; a wrong password returns success: false.

Never hardcode the password in the payload

Request bodies end up in scripts, logs, and version control. Inject unlockExcelAction.password from an environment variable or secrets manager, the same rule as any credential.

Unlock first, then automate

Other Excel actions (add rows, extract worksheets, merge files) expect an unprotected workbook. Chain ExcelUnlock as step one and feed its output downstream.

HTTP setup

Method: POST
URL: https://api.pdf4me.com/office/ApiV2Excel/ExcelUnlock
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.

Which protections does unlocking remove?

Excel protection is layered, and the layers behave differently. Unlocking with the correct password removes all of them in one pass.

Protection vs behavior	What it blocks	Removed by this API
File encryption	Opening the file at all without the password	Yes, with the correct password
Workbook structure protection	Adding, deleting, or reordering sheets	Yes
Worksheet protection	Editing cells on a locked sheet	Yes
An unknown, lost password	Everything above	No. The correct password is required

API body fields

Parameter	Required	Type	What it does	Example
`document`	Required	object	Document reference carrying Name, the protected Excel filename with its extension.	`{ "Name": "data.xlsx" }`
`docContent`	Required	string	Base64-encoded bytes of the password-protected workbook.	`UEsDBBQABgAIAAAA...`
`unlockExcelAction`	Required	object	Action configuration object holding the password and optional culture settings.	`{ "password": "..." }`
`password`	Required	string	Inside the action object. The password that was used to protect the file. Inject from a secret store; never hardcode.	`{{EXCEL_PASSWORD}}`
`cultureName`	Optional	string	Inside the action object. Culture code applied during processing.	`en-US`

Sample payloads

Unlock with a secret-injected password

{
 "document": { "Name": "data.xlsx" },
 "docContent": "UEsDBBQABgAIAAAA...",
 "unlockExcelAction": {
 "password": "{{EXCEL_PASSWORD}}"
 }
}

Unlock with an explicit culture

{
 "document": { "Name": "quarterly-report.xlsx" },
 "docContent": "UEsDBBQABgAIAAAA...",
 "unlockExcelAction": {
 "password": "{{EXCEL_PASSWORD}}",
 "cultureName": "en-US"
 }
}

Postman collection tips

Headers

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

Body

raw JSON. The password goes INSIDE unlockExcelAction, not at the root. Use a Postman environment variable for it.

Response

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

Failures

A wrong password returns success false with an errorMessage; nothing is partially unlocked and the source is untouched.

curl example

curl -X POST https://api.pdf4me.com/office/ApiV2Excel/ExcelUnlock \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "document": { "Name": "data.xlsx" },
 "docContent": "'"$(base64 -w 0 data.xlsx)"'",
 "unlockExcelAction": {
 "password": "'"$EXCEL_PASSWORD"'"
 }
 }' \
 --output response.json

What does the API return?

A JSON result carrying the unprotected workbook as Base64.

Field	Type	What it contains
`document`	String (Base64)	The unprotected workbook content. Decode to bytes and save with an .xlsx extension.
`fileName`	String	Output filename for the unlocked workbook.
`success`	Boolean	true when unlocking succeeded. Check this before decoding content.
`errorMessage`	String	Populated when success is false, including the wrong-password case.

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

Can this API unlock an Excel file without the password?+

No. The unlock action removes protection using the correct password you supply in unlockExcelAction.password. It is a workflow tool for files whose password you legitimately hold, not a password cracker or recovery service.

Which kinds of Excel protection does it remove?+

File encryption (the password prompt when opening), workbook structure protection, and worksheet protection are removed in one pass, returning a fully unprotected copy of the workbook.

Is the response the file itself?+

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

What happens if I send the wrong password?+

The operation fails: success comes back false and errorMessage explains the failure. The workbook is never partially unlocked and your source file is never modified.

Does unlocking change the workbook contents?+

No. Cells, formulas, formatting, and sheets are untouched. Only the protection layers are removed; the output is the same workbook without the locks.

How do I keep the password out of my scripts?+

Inject it at runtime: a Postman environment variable, an environment variable in shell scripts, or a secrets manager in production code. Request bodies frequently end up in logs and version control, so treat the payload as sensitive.

Can I re-protect the file after processing?+

Yes. Chain the Secure Excel action after your processing steps to apply fresh protection to the finished workbook.

Why unlock via API instead of manually?

The manual route for a sheet-level lock is unprotecting the sheet in Excel: open the file, enter the password, Review tab, Unprotect Sheet, save, repeat per file. That does not scale to a nightly folder of protected reports. The API performs the same password-verified removal as one deterministic request per file, and the output stays a standard Office Open XML workbook ready for the rest of the pipeline.

Secure Excel Document

The inverse operation: apply password protection to a finished workbook.

Extract Worksheets

A common next step once unlocked: split the workbook into per-team sheets.

Unlock PDF

The PDF counterpart: remove password protection from PDFs with the known password.