Filings API

Important! Please note, that downloading and installing any of the DarkMindFx indicator packages and/or libraries you are accepting the terms of use described on this page - Terms Of Use. Please read them carefully before downloading.
All information and data provided as well as trademarks, service marks, trade names or any other marks are the property of the corresponding agencies. We don't own them and provide it for informational purposes only.

Filings API Specification


Getting Started


Before using the API first you need to obtain the API Key. You can find it in your account details either by logging in or (if you don't have an account yet) by Registering

Once you've got the API Key the first call you should perform is InitSession and speciffy the key as a parameter of the command. In response in case if the key is valid the Session Token will be returned. This Session Token then should be provided to all the other commands.

Use the menu of the left to get the detailed specification on each API command

When you're done with you work - close the session with CloseSession call.

Session Initialization


Command:

InitSession


This is the first command to call in order to beging working with the API. It initializes the session and returns the token which will be used in all the subsequent calls. In order to initialize the session you need to provide your Account Key. You can easily obtain one by just registering here.

URI
                    /api/accounts/InitSession
POST Request:
                    {
                        "RequestID" : "Unique-Identifier"
                        "AccountKey": "Your-Account-Key"
                    }
Response:
                    {
                        "RequestID"   : "Unique-Identifier",
                        "Success"     : true,
                        "Errors"      : [],
                        "SessionToken": "New-Session-Token"
                    }

GET request:
                    /api/accounts/InitSession/{You-Account-Key}

Closing Session


Command:

CloseSession


When you're done please use this command to finalize the session.

URI
                    /api/accounts/CloseSession
POST Request:
                    {
                        "RequestID"    : "Unique-Identifier",
                        "SessionToken" : "Session-Token"
                    }
Response:
                    {
                        "RequestID"    : "Unique-Identifier",
                        "Success"      : true,
                        "Errors"       : [],
                        "SessionToken" : "Session-Token"
                    }

GET request:
                    /api/accounts/CloseSession/{Session-Token}

Error Handling


Each response contains two mandatory fields - Success and Errors. Success is the Boolean flag which can be used to quickly identify whether the request was successfully processed or not. Under normal circumstances this flag should always be "true".
Optionally there can be the case when command was executed successfully but Errors array contains some information messages or warnings. In case if any error has occured this flag will be set to "false" and Errors array will be populated with list of errors occured. Please note, that's its possible to have more than one error in the list.
Each error has the following format:
                    {
                        "Code"      : "Error-Code",
                        "Type"      : "Info/Warning/Error",
                        "Message"   : "Error-Message-Text",
                        "Timestamp" : "Date-Time-Error-Occured"
                    }

List Regulators


Command:

GetRegulators


With this command you can obtain the list of all currently supported regulators. Regulators are the government agencies which collects the companies' filings - for example U.S. SEC. This command returns list of regulators' codes, countries and names.

URI
                    /api/filings/GetRegulators
POST Request:
                    {
                        "RequestID"    : "Unique-Identifier",
                        "SessionToken" : "Session-Token"
                    }
Response:
                    {
                        "Regulators"   : [
                                {
                                 "Code":"SEC",
                                 "CountryCode":"US",
                                 "Name":"Securities and Exchange Commission"
                                }
                                ......
                        ],
                        "RequestID"    : "Unique-Identifier", 
                        "Success"      : true,
                        "Errors"       : [],
                        "SessionToken" : "Session-Token"
                    }

GET request:
                    /api/filings/GetRegulators/{Session-Token}

List Companies By Regulator


Command:

GetCompanies


Use this command to get the list of all companies supported per given regulator.

URI
                    /api/filings/GetCompanies
POST Request:
                    {
                        "RegulatorCode": "Regulator-Code",
                        "RequestID"    : "Unique-Identifier",
                        "SessionToken" : "Session-Token"
                    }
Response:
                    {
                         "Companies":[
                            {
                             "Name":"3M Company",
                             "Code":"MMM"
                            },
                            {
                             "Name":"Abbott Laboratories",
                             "Code":"ABT"
                            },
                            ....
                        ],
                        "RequestID"    : "Unique-Identifier", 
                        "Success"      : true,
                        "Errors"       : [],
                        "SessionToken" : "Session-Token"
                    }
GET request:
                    /api/filings/GetCompanies/{RegulatorCode}/{Session-Token}

List Filings By Company


Command:

GetCompanyFilingsInfo


For each company it is possible to get the list of available filings. The two mandatory fields to be provided are RegulatorCode and CompanyCode - these values can be extracted from previous calls. By default the response will returns all reports of all types availalbe in database.
Optionally it is possible to specify the time range for which filings need to be obtained - for example by specifying PeriodStart = "2016-01-01" and PeriodEnd = "2017-01-01" will give you the list of reports filed in the course of year 2016. Additionally it is possible to filter out - what types of the reports should be returned. For this purpose please specify the list of report codes in the Types field of the request.

URI
                    /api/filings/GetCompanyFilingsInfo
POST Request:
                    {
                        "RegulatorCode": "Regulator-Code",
                        "CompanyCode"  : "Company-Code",
                        "PeriodStart"  : "Period-Start-Date",
                        "PeriodEnd"    : "Period-End-Date",
                        "Types"        : [{Optional: Comma-Separate List of Types - e.g. "10-Q", "10-K"}],
                        "RequestID"    : "Unique-Identifier",
                        "SessionToken" : "Session-Token"
                    }
Response:
                    {
                        "RegulatorCode":"SEC",
                        "CompanyCode":"AAPL",
                        "Filings":[
                            {
                                "Name":"000032019317000009",
                                "Type":"10-Q",
                                "PeriodStart":"/Date(1491084000000-0000)/",
                                "PeriodEnd":"/Date(1498860000000-0000)/",
                                "Submitted":"/Date(1501624800000-0000)/"
                            },
                            ......
                        ],
                        "RequestID"    : "Unique-Identifier", 
                        "Success"      : true,
                        "Errors"       : [],
                        "SessionToken" : "Session-Token"
                    }

GET request:
                    /api/filings/GetCompanyFilingsInfo/{Regulator-Code}/{Company-Code}/{Session-Token}
                    /api/filings/GetCompanyFilingsInfo/{Regulator-Code}/{Company-Code}/{Period-Start-Date}/{Period-End-Date}/{Session-Token}
/api/filings/GetCompanyFilingsInfo/{Regulator-Code}/{Types}/{Company-Code}/{Period-Start-Date}/{Period-End-Date}/{Session-Token}

Read Company's Filing Details


Command:

GetFilingData


To get the details of each company filing use this command with following mandatory field: RegulatorCode, CompanyCode and FilingName - this combintation represent the unique identifier of each filing. All these values can be obtained from previous calls. In response the list of values with values codes are returned. Each value has its code, units of count and range of dates for which it corresponds. This range of dates can represent quarter, year-to-date or year-over-year periods.

By default the response will return the complete list of values available for the current report.
Optionally it is possible to limit the number of values returned by specifying the list of value codes in the "Values" array.

Because regulatory filings can contain not only numeric values bur also string and date/time data (like, for example, SEC Form 4) the response can contains several FilingData arrays - one per eah data type. It is also possible that more than one value describes the fact. In both of thse cases you can restore the full fact content based on the Fact_Id field which will be attached to each data record. This field is optional and will not be provided if there is just single value describing the fact (like. for example, value of the revenue for the given period)

URI
                    /api/filings/GetFilingData
POST Request:
                    {
                        "RegulatorCode": "Regulator-Code",
                        "CompanyCode"  : "Company-Code",
                        "FilingName"   : "Filing-Name",
                        "Values"       : [{Optional: Comma-Separate List of Values}],                       
                        "RequestID"    : "Unique-Identifier",
                        "SessionToken" : "Session-Token"
                    }
Response:
                    {
                        "RegulatorCode" :"SEC",
                        "CompanyCode"   :"AAPL",
                        "FilingName"    :"000032019317000009",
                        "Type"          :"10-Q",
                        "PeriodStart"   :"2019-03-31 00:00:00",
                        "PeriodEnd"     :"2019-06-29 00:00:00",
                        "Submitted"     :"2019-07-31 00:00:00",
                        "FilingData":
                        [
                            {
                                "Code":"WeightedAverageNumberOfSharesOutstandingBasic",
                                "Value":5239847000,
                                "PeriodStart":"2019-03-31 00:00:00",
                                "PeriodEnd":"2019-03-31 00:00:00",
                                "UnitName":"shares"
                            },
                            .....
                            {
                                "Code":"GrossProfit",
                                "Value":16106000000,
                                "PeriodStart":"2019-03-31 00:00:00",
                                "PeriodEnd":"2019-06-29 00:00:00",
                                "UnitName":"usd"
                            },
                            .....
                            {
                                "Code":"SalesRevenueNet",
                                "Value":168787000000,
                                "PeriodStart":"2019-03-31 00:00:00",
                                "PeriodEnd":"2019-06-29 00:00:00",
                                "UnitName":"usd"
                            },
                            .....
                        ],
                        "FilingDataStr": [
                            .....
                        ],
                        "FilingDataDttm": [
                            .....
                        ],
                        "RequestID"    : "Unique-Identifier", 
                        "Success"      : true,
                        "Errors"       : [],
                        "SessionToken" : "Session-Token"
                    }

GET request:
                    /api/filings/GetFilingData/{RegulatorCode}/{CompanyCode}/{FilingName}/{SessionToken}
                    /api/filings/GetFilingData/{RegulatorCode}/{CompanyCode}/{FilingName}/{Values}/{SessionToken}

Read Company's Financial Ratios For Given Filing


Command:

GetFilingRatios


To get the set of ratios of each company filing use this command with following mandatory field: RegulatorCode, CompanyCode and FilingName - this combintation represent the unique identifier of each filing. All these values can be obtained from previous calls. In response the list of values with values codes are returned. Each value has its code, units of count and range of dates for which it corresponds. This range of dates can represent quarter, year-to-date or year-over-year periods.
By default the response will return the complete list of ratios available for the current report.
Optionally it is possible to limit the list of ratios returned by specifying the comma separated value codes in the "Values" array.

URI
                    /api/filings/GetFilingRatios
POST Request:
                    {
                        "RegulatorCode": "Regulator-Code",
                        "CompanyCode"  : "Company-Code",
                        "FilingName"   : "Filing-Name",
                        "Values"       : [{Optional: Comma-Separate List of Ratios}],                       
                        "RequestID"    : "Unique-Identifier",
                        "SessionToken" : "Session-Token"
                    }
Response:
                    {
                        "RegulatorCode" :"SEC",
                        "CompanyCode"   :"AAPL",
                        "FilingName"    :"000032019317000009",
                        "Ratios":
                        [
                            {
                                "Code":"CurrentRatio",
                                "Value":1.25676,
                                "PeriodStart":"2017-09-30 00:00:00",
                                "PeriodEnd":"2017-09-30 00:00:00"
                            },
                            .....
                            {
                                "Code":"ProfitMargin",
                                "Value":0.18666,
                                "PeriodStart":"2017-09-30 00:00:00",
                                "PeriodEnd":"2017-09-30 00:00:00"
                            },
                            .....
                            {
                                "Code":"ROE",
                                "Value":0.08764,
                                "PeriodStart":"2017-09-30 00:00:00",
                                "PeriodEnd":"2017-09-30 00:00:00"
                            },
                            .....
                        ],
                        "RequestID"    : "Unique-Identifier", 
                        "Success"      : true,
                        "Errors"       : [],
                        "SessionToken" : "Session-Token"
                    }

GET request:
                    /api/filings/GetFilingRatios/{RegulatorCode}/{CompanyCode}/{FilingName}/{SessionToken}
                    /api/filings/GetFilingRatios/{RegulatorCode}/{CompanyCode}/{FilingName}/{RatioCodes}/{SessionToken}

Read Company's Common Size Balance Sheet


Command:

GetCommonSizeBalanceSheet


To get the set of ratios of each company filing use this command with following mandatory field: RegulatorCode, CompanyCode and FilingName - this combintation represent the unique identifier of each filing. All these values can be obtained from previous calls. In response the list of values with values codes are returned. Each value has its code, units of count and range of dates for which it corresponds. This range of dates can represent quarter, year-to-date or year-over-year periods.
By default the response will return the complete list of recalculated to common size assets, liabilities and equity parts of balance sheet available for the current report.


URI
                    /api/filings/GetCommonSizeBalanceSheet
POST Request:
                    {
                        "RegulatorCode": "Regulator-Code",
                        "CompanyCode"  : "Company-Code",
                        "FilingName"   : "Filing-Name",                     
                        "RequestID"    : "Unique-Identifier",
                        "SessionToken" : "Session-Token"
                    }
Response:
                    {
                        "RegulatorCode" :"SEC",
                        "CompanyCode"   :"AAPL",
                        "FilingName"    :"000032019317000009",
                        "Ratios":
                        [
                            {
                                "Code":"AccountsReceivableNetCurrent",
                                "Value":0.0634,
                                "PeriodStart":"2017-09-30 00:00:00",
                                "PeriodEnd":"2017-09-30 00:00:00"
                            },
                            .....
                            {
                                "Code":"Assets",
                                "Value":1,
                                "PeriodStart":"2017-09-30 00:00:00",
                                "PeriodEnd":"2017-09-30 00:00:00"
                            },
                            .....
                            {
                                "Code":"Liabilities",
                                "Value":0.4,
                                "PeriodStart":"2017-09-30 00:00:00",
                                "PeriodEnd":"2017-09-30 00:00:00"
                            },
                            .....
                            {
                                "Code":"LiabilitiesAndStockholdersEquity",
                                "Value":1,
                                "PeriodStart":"2017-09-30 00:00:00",
                                "PeriodEnd":"2017-09-30 00:00:00"
                            },
                        ],
                        "RequestID"    : "Unique-Identifier", 
                        "Success"      : true,
                        "Errors"       : [],
                        "SessionToken" : "Session-Token"
                    }

GET request:
                    /api/filings/GetCommonSizeBalanceSheet/{RegulatorCode}/{CompanyCode}/{FilingName}/{SessionToken}


Developer Resources


Microsoft .NET Library

Download

For all .NET developers we offer easy to use library which incapsulates Filings API functionality and provides convinient Data Transfer Objects (DTOs).

The library is distributed as a Nuget package and can be easily integrated using following command:


    Install-Package DMFX.APIClients -Version 2019.11.18
                

You can also download the Nuget package from our site using Download button.

Python Scripts

Download

Like scripting? Then Python script for Filings API access is just for you. Download our Python script and start consuming the financial data in a matter of minutes .




Java Library

Download

Coming Soon!


Developing the financial applications in Java? Don't worry! We are striving to bring you the best quality we can - that's why we are taking time to develop a really usful and convinient Java library. We'll deliver the libary for you shortly. So stay tuned!