URI Format
This is a general format of URL to DataFied API
{Protocol}://datafied.api.edgar-online.com/{Version}/{Endpoints}{Format}?{Parameters}appkey={API Key}
| Name | Description | Required | Default Values |
| Protocol |
HTTP and HTTPS |
Yes |
|
| Version |
Version of API: v2 or v1 |
Yes |
v2 |
| Endpoints, Parameters |
Path to API method and parameters |
Yes |
Each API call is documented under each API resource |
| Response format |
Format of API response: .json or .xml |
No |
JSON|XML, Default response format is JSON |
| API Key |
Authorized API Key |
Yes |
|
Please note that URLs need to be URL-encoded for every request.
Response Format
All DataFied APIs return JSON formatted responses, unless otherwise specified in the call being made.
https://datafied.api.edgar-online.com/v2/companies?primarysymbols=msft&appkey={APPKEY}
{
"result": {
"totalrows": 1,
"rows": [
{
"rownum": 1,
"values": [
{
"field": "cik",
"value": "0000789019"
},
{
"field": "companyname",
"value": "MICROSOFT CORP"
},
{
"field": "entityid",
"value": 8528
},
{
"field": "primaryexchange",
"value": "Nasdaq Global Market"
},
{
"field": "primarysymbol",
"value": "MSFT"
},
{
"field": "siccode",
"value": "7372"
},
{
"field": "sicdescription",
"value": "Prepackaged Software"
}
]
}
]
}
}
DataFied supports two formats: JSON and XML. To specify one format versus the other, please reference the examples listed below.
JSON
1. Specifying .json sufix
https://datafied.api.edgar-online.com/v2/companies.json?primarysymbols=msft&appkey={APPKEY}
2. Specifying headers
GET /v2/companies?primarysymbols=msft&appkey={APPKEY} HTTP/1.1
ApplicationKey: {APPKEY}
Host: datafied.api.edgar-online.com
Accept: application/json
Response
{
"result": {
"totalrows": 1,
"rows": [
{
"rownum": 1,
"values": [
{
"field": "cik",
"value": "0000789019"
},
{
"field": "companyname",
"value": "MICROSOFT CORP"
},
{
"field": "entityid",
"value": 8528
},
{
"field": "primaryexchange",
"value": "Nasdaq Global Market"
},
{
"field": "primarysymbol",
"value": "MSFT"
},
{
"field": "siccode",
"value": "7372"
},
{
"field": "sicdescription",
"value": "Prepackaged Software"
}
]
}
]
}
}
XML
1. Specifying .xml sufix
https://datafied.api.edgar-online.com/v2/companies.xml?primarysymbols=msft&appkey={APPKEY}
2. Specifying headers
GET /v2/companies?primarysymbols=msft&appkey={APPKEY} HTTP/1.1
ApplicationKey: {APPKEY}
Host: datafied.api.edgar-online.com
Accept: application/xml
Response
<response>
<result>
<totalrows>1</totalrows>
<rows>
<row>
<rownum>1</rownum>
<values>
<value field="cik">0000789019</value>
<value field="companyname">MICROSOFT CORP</value>
<value field="entityid">8528</value>
<value field="primaryexchange">Nasdaq Global Market</value>
<value field="primarysymbol">MSFT</value>
<value field="siccode">7372</value>
<value field="sicdescription">Prepackaged Software</value>
</values>
</row>
</rows>
</result>
</response>
URI Examples
https://datafied.api.edgar-online.com/v2/corefinancials/ann?primarysymbols=MSFT&appkey={APPKEY}
https://datafied.api.edgar-online.com/v2/corefinancials/qtr?primarysymbols=MSFT&numperiods=3&appkey={APPKEY}
https://datafied.api.edgar-online.com/v2/companies?primarysymbols=MSFT&appkey={APPKEY}
https://datafied.api.edgar-online.com/v2/insiders/filers?issueids=539631&appkey={APPKEY}
Useful API Calls
Debug
Debug parameter helps developers investigate what happened during the call and what items were substituted if any during the call.
https://datafied.api.edgar-online.com/v2/corefinancials/ann.json?primarysymbols=MSFT&numperiods=3&debug=true&appkey={APPKEY}
"debug": {
"primarysymbols":"MSFT",
"numperiods":"3",
"sortby":"PRIMARYSYMBOL ASC, PERIODENDDATE DESC",
"limit":"25",
"deleted":"false",
"offset":"0",
"fields":"CIK,COMPANYNAME,ENTITYID"
}
Pagination
When the amount of data returned in response is larger than the system defined rows, data pagination occurs. Navigation to a certain row in the paginated result set is possible via two parameters in the request for any resource: limit and offset. Limit defines the number of rows to be returned. Offset defines how many rows to skip as means to navigate to the specific page of results. Every response displays total number of rows in the system.
Limit
By default, if a developer does not specify any limit value, the system returns the first 25 rows. In other cases they can define an integer as a limit, using a value between 1 and 9999.
Example:
https://datafied.api.edgar-online.com/v2/companies?companynames=*micro*&limit=10&appkey={APPKEY}
This request will return 10 rows from total list of companies, with "micro" contained in the name.
Invalid request:
https://datafied.api.edgar-online.com/v2/companies?companynames=*micro*&limit=10000&appkey={APPKEY}
Response:
400 Bad Request
X-DataFied-Error-Code: ERR_403_DEVELOPER_INACTIVE
{
"Message": "Parameter 'limit' has invalid value. Parameter should contain a value within the range of 1 - 9999."
}
Offset
If the total number of expected rows is a large value offset parameter can be useful to narrow the result set. By default the system returns 25 rows per page with offset = 0. To navigate to the page 2 of the request, set the offset = 26, which will pull data rows between 26 and 50. For page 3, define the offset = 51; each subsequent page can be called by using increments of 25.
Example:
https://datafied.api.edgar-online.com/v2/companies?companynames=*micro*&offset=25&appkey={APPKEY}
Parameter offset cannot be larger than 9,000,000,000,000,000,000.
Invalid request:
https://datafied.api.edgar-online.com/v2/companies?companynames=*micro*&offset=9000000000000000001&appkey={APPKEY}
Response:
400 Bad Request
{
"Message": "Parameter 'offset' has invalid value. Parameter should contain only a valid integer value within the range of 0 - 9000000000000000000."
}
To output a large number of rows use the both limit and offset parameters.
Example:
https://datafied.api.edgar-online.com/v2/corefinancials/ann?primaryexchanges=OTCBB&numperiods=2&offset=100&limit=9999&appkey={APPKEY}
The call above will return all the rows starting from 101.
Threshold
Threshold is the technical limit that will generate a“400 Bad Request” error when the output, with filters applied, is greater than or equal to 1,000 records. "Limit" parameter is used if only threshold limit are met.
Threshold limits are applied to the all Core and Insider resources; there are two exceptions - Ownership-CurrentIssueHolders and Ownership-CurrentOwnerHoldings - which are not limited to the 1,000 row limit.
Example:
https://datafied.api.edgar-online.com/v2/corefinancials/ytd?fields=BalanceSheetConsolidated&activecompanies=false&deleted=false&appkey={APPKEY}
Response:
400 Bad Request
{
"Message": "Please refine your search criteria as results exceed the maximum threshold for rows. Results limited to 1000 rows."
}
SortBy:
All resources support the sortby parameter as a filter to the request. Users can sort by any given requested field if they are entitled for the field.
https://datafied.api.edgar-online.com/v2/companies?companynames=*micro*&limit=10&offset=10&sortby=companyName asc&appkey={APPKEY}
Negation:
Negation defines "exclude” or “include" any additional field in the response.
Negation are defined by adding a ! in front of the fields parameter; if including any additional fields then just specify the fieldname without ! in the fields parameter. Please note that user must be entitled for the field if they are adding any fields in response.
Example:
To remove the CIK from the response:
https://datafied.api.edgar-online.com/v2/companies?fields=!cik&companynames=*micro*&appkey={APPKEY}
To display only website url in the response:
https://datafied.api.edgar-online.com/v2/companies?fields=websiteurl&companynames=*micro*&appkey={APPKEY}