Getting started with the XBRL Filed Data Add-in for Excel

[David Tauriello]

Installation:

Install the XBRL Filed Data Add-on for Excel || Get these instructions in PDF

Watch a quick setup demo outlining how to install and get started with the XBRL Filed Add-in for Excel.
1. Open an Excel file from M365 or Office365, choose the Insert menu, click the Get Add-ins button, search for ‘XBRL’ and install XBRL Filed Data.
    
2. Click the XBRL Filed Data menu option, then Get a Free Account and follow the instructions on that page. Everyone, regardless of XBRL US Membership status, is welcome to request provisioning to use the XBRL API.
   

   All XBRL US Member accounts should be able to login and generate client ID and secret pairs. If you’re not able to do this, follow the prompt and request provisioning for this in email.

3. After the Add-in installs, click the XBRL Filed Data menu option to show the ribbon.
    
4. Click the login link in the ribbon to show the Query Wizard task pane.
   

   If you don’t have an XBRL US Web account provisioned to generate client ID and secret pairs, click the Get Account and Credentials button in the ribbon and follow the instructions on the web page.

5. Click the login button on the task pane and enter your XBRL US Web account email, password, client ID and secret, then click the login button at the bottom of the popup window. NOTE: If you use our ‘Sign in with Google’ option, you cannot use your Google account (gmail and password) to authenticate. You must use your Gmail email and XBRL US password.
    
6. Choose one of the functions in the task pane from the dropdown, at least one filter criteria, and the fields that should populate from the ‘Data to Return’ section of the Query Wizard task pane, then click the Search button.

Troubleshooting:

If you’re having trouble getting data to appear, try the following in the listed order, and stop when your issue is resolved:

1. If your account has recently been provisioned and you’re unable to generate client ID and secret pair to use in the Add-in, try using a private/incognito browser window or a different browser to login to the XBRL US web page where these pairs are created (or clear your browser’s cache). If you’re logged in to the interface and cannot create a Client ID and secret, you may have created a password with a character that is not allowed. Update your password to use only letters and numbers (no punctuation marks) – https://xbrl.us/reset-password.
    
2. Use this online script (or this version of the same resource) to confirm you have valid credentials (email, password, client ID and secret) for XBRL API authentication. You only need to run the first gray box and enter your information as it is requested. If you get a message that ‘There was a problem generating an access token with these credentials’, you’ll need to change your password and/or re-generate a Client ID and secret.
    
3. If you’re using the ‘Sign on with Google’ option to login on the XBRL US Web site, make sure you have created an XBRL US Web account with a password (you can use the same email as your ‘Sign on with Google’ email, but it is recommended that you not re-use your Google account password as your XBRL US Account password) and use the XBRL US Web account email and password as the login for the Add-in.
    
4. If you login on the Add-in and the Query Wizard doesn’t show ‘Data to Return’ options, right-click the task pane and choose reload, then click the logout button. After this, click the login button. Still not working? Uninstall the Add-in, close, re-open and re-install the Add-in.
    
5. If you return to Excel and the Add-in task panel shows ‘Unable to open’ the Add-in, click close on the panel, then choose ‘Login / Query Wizard’ to re-initialize the Add-in.
    
6. Clear the cache in your browser (DESKTOP Users – clear the Microsoft Edge browser cache), then close and re-open Excel and the Add-in.

Tried everything and it still won’t work? Post a reply here.

• This topic was modified 3 years, 2 months ago by David Tauriello.
• This topic was modified 3 years, 2 months ago by David Tauriello.
• This topic was modified 3 years, 2 months ago by David Tauriello.
• This topic was modified 3 years, 2 months ago by David Tauriello.

[Laura Rusu]

Hi David,
This is really great!
How many data points can non-members request (as opposed to members)? are there any other restrictions for non-members?
Thank you,
Laura

[Samuel Pun]

Hi David,
I’m using Excel XBRL add-in. I can log in and I can grab data by using the panel and creating the query using the panel. However, when using the actual API query in Excel, it doesn’t seem to work. It doesn’t even recognise the formula since it shows #NAME?. Any ideas?
Thanks,
Sam

[David Tauriello]

Hi Sam – a couple of things to check:

1. If you’re re-using queries from Google Sheets, the function is slightly different in Excel (=showData vs. =XBRL.showData)
2. Excel limits the length of formulas to 255 characters. Our query generator breaks these up, but you may be using one that goes beyond this limit. To get around this, drop your formula in a cell (A1) and use =XBRL.showData(A1, “”, “”, “1”) to return the data. NOTE: the subsequent parameters are required in Excel, even if they’re empty.

If neither of these helps, post the forumula you’re using in a reply here.

[Samuel Pun]

Hi David,
I’m using Excel. The auto generated formula is, for example, =XBRL.ShowData(“https://api.xbrl.us/api/v1/entity/search?entity.cik=0001799332&fields=entity.name,entity.limit(),entity.offset()&”,””, “”, “1”)

no issue with number of characters as it’s <255.

i think Excel is not recognising =XBRL.ShowData or any add-in functions.

Werid thing is that I can request data but just not using the functions.

Not sure if it’s because I’m using Excel 2019?

Regards,
Sam

[David Tauriello]

Hi Sam – thanks for the additional detail and yes, your version of Excel is not compatible with the add-in – I’ve written to Microsoft to see why the add-in is available to users who cannot use it.

The query you posted will work in Excel for Office 365. If you create a free account with Microsoft – https://www.office.com/launch/excel – you can install the add-in and use it with the web version of Excel.

[David Tauriello]

Hi Laura – thanks for writing and I’m glad you’re interested in the XBRL Data Filed add-in for Excel.

This is from the Terms of Use Agreement that governs access and us of our Public Filings Database:

XBRL US Membership improves data access (see below). Sole Practitioners and Organizational Members also enjoy publishing rights and commercial use of data returned from our Database of Public Filings.

Membership Type	Records per query	Record offset limit
non-Member *	100	1,000
Basic Individual *	500	2,000
All Other Members	2,000	unlimited

* Account limit: 100,000 queries

In addition, the /document endpoint is not accessible to non-Members. Check out the documentation for full details on the XBRL API specification – https://xbrlus.github.io/xbrl-api

[Laura Rusu]

Thank you very much, David!

Kind regards,
Laura

[Farrukh Javaid]

Hello David,
I cannot login on the XBRL API in the excel sheet despite using the current account credentials / ClientID / Client Secret etc. Every time I try to login it says login failed.
Can you please help as how to further proceed with the login and use data?
Thank you.

Best Regards
Farrukh Javaid

[David Tauriello]

Hi Farrukh – please try the troubleshooting steps listed above, starting with using a private or incognito browser window to login and generate pairs at https://xbrl.us/access-token – make sure you login with your XBRL US Web account credentials (email and password), and not the ‘Sign in with Google’ option, and also be sure you have logged in with the same email address you used to request provisioning for your account.

[Elisa Roselli]

Hi David,
I’m trying to install the Excel add-in. I keep getting an error “We can’t load this add-in because we couldn’t connect to the catalog”. The Excel spreadsheet shows the XBRL Filed Data tab, but it won’t let me log in (just repeats the error in the wizard window).
I am currently logged in on the xBRL web site and am a member of xBRL US. Is there a way around this?
Thanks,

Elisa Roselli

[David Tauriello]

Hi Elisa – thanks for sending along the error message. In short, ‘we couldn’t connect to the catalog’ means the issue is in getting connected to the Microsoft Store to download the add-in.

If your Microsoft Office license is held by an organization, there may be a restriction in place that prevents the use of Add-ins for security; in that case, you’ll need to work with your IT Team to request the Add-in be admin managed – this should make it available to you and anyone else in your organization.

If your Microsoft Office license is yours personally, there may be a network restriction in place, and your IT Team would need to allow traffic to and from our domain and github (where the scripts for the add-in are stored). NOTE: while you might be able to install and use the add-in if the computer is outside of the network or VPN, but it might not function once the computer is back inside the network.

We’ve had reports that while the add-in is blocked for download on the desktop, it is functional as an add-in using Excel on the web – https://www.office.com/launch/excel

I hope this helps.

[Elisa Roselli]

Hi David,

Still no joy, either online or local. Do you know the URL of the catalog? In the Office Trust Center, I find a page where I can set up “Trusted Web Add-in Catalogs”, by providing the catalog URL, but https://xbrl-us.org doesn’t work.

I am trying to get help from my company’s IT support, but they can’t make heads or tails of this problem. The only solution suggested so far was to uninstall and reinstall the whole Office 365 suite, which took much of yesterday and didn’t help at all.

[David Tauriello]

Hi Elisa – I’m not aware of any Trust Center settings that make the published add-in work.

Are you able to download, install and use other add-ins from the Office Store (https://appsource.microsoft.com/en-us/marketplace/apps?product=office%3Bexcel&page=1)?

A Google search of the phrase you’re getting shows this as the top result among several that indicate the same information – that access is blocked by local policy, either on the network or in the Office 365 suite (nb. the add-in won’t work with earlier versions on Windows … could it be that this is the issue in your setup – ?): https://support.papersapp.com/support/solutions/articles/30000040701-troubleshooting-error-message-we-can-t-load-this-add-in-because-we-couldn-t-connect-to-the-catalog

Assuming the issue is not related to the corporate firewall, here’s what Microsoft says needs to be done to make the Add-in available as admin-managed: https://docs.microsoft.com/en-us/microsoft-365/admin/manage/manage-deployment-of-add-ins?view=o365-worldwide

To use the Excel Add-in without having your IT Team approve it for use in your company’s Office 365 profile, you can create a free account at https://live.com while you are on a computer that is not connected to a company network or VPN – like Google, Microsoft gives access to Office on the Web to registered users.

Once you’ve logged in with your new Microsoft account to Excel on the Web, install the XBRL Filed Data add-in, then log in to the XBRL Filed Data add-in using your XBRL US Web account credentials and the client ID and secret you generated from our site.

Assuming the new Microsoft account is not connected to your company and your connection to the Internet is not routing through your corporate LAN or VPN, you should be able to use the Excel Add-in.

[Magy Avedissian]

Hi David,

I seem to be having issues logging into the extension through Excel. I have tried generating a key in incognito mode and have made sure I am not logging in through the “Sign in through Google” option. Any advice?

Thanks!

[David Tauriello]

Hi Magy – you need to use Office 365 Excel and have all four pieces of information when you login to the add-in (XBRL US Web account email, password, client ID and secret). When you click the login button on the add-in task pane, a window should appear over the top of the spreadsheet (if you’re on the web, it may be below your browser window).

If you’re opening one of our templates from the web with Office live, you’ll first need to make a copy of it to your account (they are read-only).

Otherwise, please let me know what specific error you’re getting, and what version of Excel you’re using. Also please note if you’re on desktop or web version of Excel.

Sincerely,
David

[Evgeny Makarov]

I can’t use the Add-In in my desktop Excel (Version 2303 Build 16.0.16227.20202 64-bit – recently updated with my 365 subscription).

I was able to login on the XBRL Filed Data – Query tab.
Then I entered, for example, the following formula using the template on the Query tab:
=XBRL.showData(“https://api.xbrl.us/api/v1/report/search?entity.code=0000320193&report.document-type=10-K,1,E-AR&fields=report.document-type,report.entity-name,report.filing-date,report.html-url,report.id&&#8221;,””, “”, “1”)

And received the following error: #NAME.

By the way, the formula works when I use Excel online, therefore I’m sure it’s not a login issue.

[David Tauriello]

Hi Evgeny – there was some maintenance being done yesterday around the time of your post. Please try again.

If you login again on your desktop Excel and are still having issues with the custom formula =XBRL.showData() not being recognized (which causes the #NAME issue), right-click on the gray background of the add-in and look for a < button in the top-right corner of the add-in - use this menu to reload the add-in. If you're still having issues, please try to join me on Monday afternoon from 3:30 - 4:30 PM ET - the link is on the right side of this page.

[Evgeny Makarov]

David,

Thank you for your reply.
I did as you instructed but it didn’t do the trick. I will try to join the online support session next Monday.

[David Tauriello]

Hi Evgeny – you could also try un-installing and re-installing the add-in. If there’s been a file corruption in the cache storing the add-in, this might clear the issue.

[Evgeny Makarov]

David,

Thank you. I just tried with no improvement.
I hope to catch up online on Monday.

[John Senger]

Hello. I have installed this add-in from the microsoft store. How do I uninstall it? I don’t see it listed on my list of add-ins.

[David Tauriello]

Hi John – if the add-in doesn’t appear under the My Add-ins option on the Excel insert menu/ribbon, it is not installed and no action is necessary.

[Rogelio Paulino]

Hi David, I still can’t access the XBRL API using the Excel add-ins. I checked my credentials using the online script. It says: ”There was a problem generating an access token with these credentials”. I already tried resolving this by using the new password and then the newly generated client ID and secret ID. Still unsolved.

[David Tauriello]

Hi Pau – thanks for writing. Please login at https://xbrl.us/access-token and create a new Client ID and secret pair. Use these new strings when you authenticate with email, password, client ID and secret in the Excel add-in or scripts.

[Bhushan Huparikar]

Hi,

Is the excel add-in or XBRL US API compatible with querying data for FERC filing data schedules?

• This reply was modified 4 months ago by Bhushan Huparikar.

[David Tauriello]

Hi Bhushan – yes, we copy every Form 1, 2, 6, 60 and 714 report submitted to FERC into our Public Filings Database. The report.source-name filter can be set to extract only FERC data.

[Author]

Posts