# Installing Address Cleanse for Microsoft Excel Cleanse, validate and enrich addresses directly inside a workbook. The add-in calls the [Cleanse API](/docs/api/address-cleanse.md) and writes 31 columns per row - status, formatted address, confidence and fit, per-element match levels, geocodes, UPRN/UDPRN, and country - as plain static values alongside your input. Your browser does not support the video tag. ## Overview[​](#overview "Direct link to Overview") **What this integration provides:** * A **Cleanse** button on the Home ribbon that opens a task pane * A **Cleanse Selection** action in the pane - runs cleanse over your selected address column and writes 31 columns of structured results immediately to the right * A **Write Headers** action - drops the 31 column labels starting at the active cell * Results are written as **plain static values**, so the workbook can be saved, shared and reopened by anyone - no add-in or API Key required to view the cleansed data **Works with:** * Excel for the Web ([excel.office.com](https://excel.office.com)) * Excel for Windows (Microsoft 365) * Excel for Mac (Microsoft 365) info The add-in is currently installed by **sideloading the manifest** (instructions below). A Microsoft AppSource listing is in progress - once published, one-click install from inside Excel will be available. Behaviour is identical either way. *** ## Screenshots[​](#screenshots "Direct link to Screenshots") ### Cleanse Selection in action[​](#cleanse-selection-in-action "Direct link to Cleanse Selection in action") ![Excel for the Web with five addresses selected and the Cleanse Selection button ready to run](/img/excel-cleanse-selection-screenshot.png) ### Ribbon button[​](#ribbon-button "Direct link to Ribbon button") ![Cleanse button on the Home ribbon under the Ideal Postcodes group](/assets/images/excel-ribbon-button-f73b909a3344e391f5ada6588e94d46d.png) ## 1. Sign up and get your API Key[​](#1-sign-up-and-get-your-api-key "Direct link to 1. Sign up and get your API Key") You need an Ideal Postcodes API Key before the add-in can return results. 1. Sign up for a free account at [ideal-postcodes.co.uk](https://account.ideal-postcodes.co.uk/users/sign_up) 2. Open the **Keys** section in your dashboard 3. Copy your API Key - it begins with `ak_` (live) or `ak_test` (test) 💡 **All new accounts include free test credits - no payment required to try the add-in.** ## 2. Install the add-in (sideload the manifest)[​](#2-install-the-add-in-sideload-the-manifest "Direct link to 2. Install the add-in (sideload the manifest)") Until the AppSource listing is published, the add-in is installed by uploading a manifest file to Excel. The manifest is hosted at: ``` https://excel.ideal-postcodes.co.uk/manifest.xml ``` You can either upload the file directly, or download it and upload it from disk. ### Excel for the Web (recommended)[​](#excel-for-the-web-recommended "Direct link to Excel for the Web (recommended)") The simplest path. No download required. 1. Download the manifest from [excel.ideal-postcodes.co.uk/manifest.xml](https://excel.ideal-postcodes.co.uk/manifest.xml) (right-click → **Save link as…**) 2. Open [excel.office.com](https://excel.office.com) and create or open a workbook 3. From the ribbon, choose **Add-ins** ![Excel for the Web Add-ins flyout showing the popular add-ins catalogue](/assets/images/excel-web-addins-menu-52a0fc74f1b52f4f68b8692ea441b3b0.png) 4. In the dialog, switch to **My Add-ins**, then click **Upload My Add-in** ![Office Add-ins dialog in Excel for the Web with the Upload My Add-in link highlighted](/assets/images/excel-web-upload-my-addin-d7c4433c8814323f483b034c2ceb6734.png) 5. Browse to the `manifest.xml` file you just saved and click **Upload** 6. The **Cleanse** button appears on the **Home** ribbon, inside the **Ideal Postcodes** group ![Cleanse button on the Home ribbon under the Ideal Postcodes group](/assets/images/excel-ribbon-button-f73b909a3344e391f5ada6588e94d46d.png) Desktop install: testing route for now Excel for Windows and Excel for Mac currently require **sideloading the manifest** - treat the steps below as a testing route while we work towards an AppSource listing. Once published, one-click install from inside Excel will be available on both platforms. [Contact us](mailto:support@ideal-postcodes.co.uk) to be notified when the AppSource release is live. ### Excel for Windows[​](#excel-for-windows "Direct link to Excel for Windows") 1. Save the manifest from [excel.ideal-postcodes.co.uk/manifest.xml](https://excel.ideal-postcodes.co.uk/manifest.xml) to a folder on your machine - for example `C:\OfficeAddins\` 2. Open File Explorer and navigate to that folder 3. Right-click the folder → **Properties** → **Sharing → Share** and share it with yourself (Excel for Windows requires sideloaded manifests to live in a shared folder - even sharing with `Everyone` on the same machine works). Copy the resulting `\\COMPUTERNAME\OfficeAddins` path. 4. In Excel, go to **File → Options → Trust Center → Trust Center Settings → Trusted Add-in Catalogs** 5. Paste the share path into **Catalog URL**, tick **Show in Menu**, click **Add catalog**, then **OK** 6. Restart Excel 7. Open **Insert → Add-ins → My Add-ins → SHARED FOLDER** and choose **Ideal Postcodes Cleanse** Full Microsoft walkthrough: [Sideload an Office Add-in on Windows](https://learn.microsoft.com/en-us/office/dev/add-ins/testing/create-a-network-shared-folder-catalog-for-task-pane-and-content-add-ins). ### Excel for Mac[​](#excel-for-mac "Direct link to Excel for Mac") 1. Save the manifest from [excel.ideal-postcodes.co.uk/manifest.xml](https://excel.ideal-postcodes.co.uk/manifest.xml) 2. In Finder press **⇧⌘G** and paste: ``` ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef ``` If the `wef` folder doesn't exist, create it. 3. Copy `manifest.xml` into that folder 4. Restart Excel 5. Open a workbook and choose **Insert → Add-ins → My Add-ins → Developer Add-ins → Ideal Postcodes Cleanse** Full Microsoft walkthrough: [Sideload an Office Add-in on Mac](https://learn.microsoft.com/en-us/office/dev/add-ins/testing/sideload-an-office-add-in-on-mac). ## 3. Sign in[​](#3-sign-in "Direct link to 3. Sign in") 1. Click the **Cleanse** button on the **Home** ribbon - the task pane opens on the right ![Disconnected Connect your account panel with empty API key field](/assets/images/excel-task-pane-disconnected-fc4519492aa71f2152d6256adb06cfcd.png) 2. Paste your API Key into the field and click the save icon (or press **Enter**) 3. The **Disconnected** badge flips to **Connected** once the key is verified, and the action buttons become active The key is stored in `OfficeRuntime.storage`, scoped to your user and the add-in. It is **never** written into a cell or into the workbook file, and it is never sent anywhere other than the Ideal Postcodes API. Sharing the workbook does not share the key. ![Cleanse button on the Home ribbon with the task pane open and showing the Connected state](/assets/images/excel-task-pane-connected-8f06af799a82319debb4b72430bc81c7.png) ## 4. Cleanse a column of addresses[​](#4-cleanse-a-column-of-addresses "Direct link to 4. Cleanse a column of addresses") 1. Highlight the cells containing your addresses 2. (Optional) Click **Write Headers** first to drop the 31 column labels at the active cell - useful for placing a header row above your data 3. Click **Cleanse Selection** in the task pane 4. The 31 result columns are written as plain values into the cells immediately right of your selection ![Excel workbook showing input addresses on the left and 31 columns of cleansed results written immediately to the right](/img/excel-cleanse-results.png) A progress banner in the task pane shows `Cleansing X / Y…` while the run is in flight. When it finishes, you'll see `Cleansed N rows.` (or `Cleansed N rows · M failed.` if any rows errored). ### Selection shapes[​](#selection-shapes "Direct link to Selection shapes") **One column of freeform addresses:** | A | | ------------------------------ | | 10 Downing St, London SW1A 2AA | | Buckingham Palace Rd, London | | ID1 1QD | Cleanse Selection writes results into `B:AF`. **Two columns - address + postcode hint:** | A | B | | ----------------- | -------- | | 10 Downing St | SW1A 2AA | | Buckingham Palace | SW1A 1AA | The second column is used as a postcode hint to disambiguate matches. Cleanse Selection writes results into `C:AG`. If you select more than two columns, the run aborts with an error in the task pane - the add-in won't guess which column is which. ## 5. Error messages[​](#5-error-messages "Direct link to 5. Error messages") Per-row failures are written inline: the `status` column for that row reads `Error: ` and the remaining 30 columns are blank. The task pane summarises the total failed count when the run finishes. Add-in-wide failures are shown as a red banner in the task pane. | Message | What it means | | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `No API key set. Sign in above to continue.` | The task pane has no key stored. Paste one into the field above and save. | | `Invalid or unauthorised API key` | Key is malformed, revoked, or the active key restrictions exclude the request. Check your [Keys dashboard](https://ideal-postcodes.co.uk/account). | | `Cleanse credit exhausted` | The key has no available Cleanse credit. [Top up](/docs/guides/automated-topups.md) or upgrade. | | `Select one column of addresses, or two columns (address + postcode hint).` | The selection has more than two columns. Re-select 1 or 2 columns and try again. | info Need help? Contact our support team via live chat on our website or email .