Overview

Introduction

Welcome to the Beta version of the TagniFi API.

Our API’s sole purpose is to deliver highly-accessible, accurate and timely financial data; enabling you to build the next-generation of financial applications.  To achieve this our API adheres to the following set of core tenets:

  • Usability -  We revere the idea of making our API as accessible and discoverable as possible. We value explicitness over implicitness. We want to provide the best API documentation, tools, and developer experience this side of the Internet.
  • Adaptability – The world changes and so will our API. We enable this change by subscribing to the hypermedia camp. It’s our intent to evolve without breaking your application.
  • Responsiveness – Our API should respect the temporal sensitivity of financial data. This means a couple of things, we will enable your application to have access to the latest financial data as it becomes available and we treat our performance as a critical success factor.

We take these tenets seriously. With that said, if you think we are missing the mark on any of these, please let us know.

A couple of other quick technical bullet points about our API, we do the following:

  • We currently only support JSON and follow the JSON API  hypermedia standard.
  • Authenticate via Basic Auth over SSL.
  • Heavily leverage HTTP status codes for all responses.
  • Versioning is handled via link relations and link deprecation policies.

What’s Next?  Well, you can get started, provide feedback, or if anything is unclear, ask questions.

Back To Top

Getting Started

Follow these steps to get started with the Beta version of the TagniFi API:

  1. Obtain an API key.
  2. Visit the Authentication page to understand  how to send your API key to any Tagnifi API action.
  3. Read the Search Fundamentals documentation.
  4. Send your first request. To test it out before you write any code you can use a number of tool(s). If you like the command line give cURL a try. If a web interface whets your appetite then give Postman a spin. If neither of these work for you there are plethora of other choices.
  5. That’s it! Request away.

Also, remember, we are in Beta, if you find any issues or have any feedback, please let us know.

Don’t forget to subscribe to our system status updates!

Back To Top

Authentication

You authenticate to the Tagnifi API via HTTP Basic Auth over HTTPS. Please send your API key via the basic auth username; the basic auth password is not required.

Note: all requests must be made via HTTPS and must be authenticated. We don’t support HTTP and  all HTTP requests will fail.

Back To Top

Actions

Search Fundamentals

Description

Searches for fundamental value(s) for specific fiscal periods (annual, quarter, or year to date). It also supports the ability to find all fundamentals for multiple periods and all fundamentals for specified statements.

Request Format

Attributes

Attribute
Description
Type
Required?
Default
Notes
companyThe company's ID or ticker symbol.StringYesPlease use our Coverage List to search for companies with data available.
tagReturns a specific tag from the TagniFi Fundamentals dataset.StringNoPlease see TagniFi Fundamentals Definitions for a list of available tags.
statementReturns all tags in the selected financial statement from the TagniFi Fundamentals dataset. StringNoSearches all statementsPossible values: balance_sheet_statement, income_statement, or cash_flow_statement.
period_typeThe type of period to search. Valid periods include annual, quarter, or year_to_date.StringYes
fiscal_yearThe fiscal year of the period you are requesting.IntegerNoMost recent fiscal_year.
fiscal_quarterThe fiscal quarter of the period you are requesting.IntegerNoMost recent fiscal_quarter.This attribute is ignored if annual is specified for the period_type.
periodsThe number of consecutive periods to be returned.IntegerNoMost recent period.All periods returned are relative to the specified fiscal_year and fiscal_quarter.

Response

Returns a fundamental resource if there are no errors. It will return an error if the request fails.

Example Request/Response

Search Fundamentals Tag Example

Search Fundamentals Statement Example

Search Fundamentals Multiple Periods Example

Back To Top

Get Company

Description

Gets information about a single company.  You should arrive at this action from navigating the links of either the “Search Fundamentals” or Get Filing“ actions.

Request Format

Attribute
Description
Type
Required?
Default
Notes
idThe ID of the company.StringYes

Response

Returns a company resource if there are no errors. It will return an error if the request fails.

Example Request/Response

Get Company Example

Back To Top

Get Filing

Description

Gets filing information about a single filing.  You should arrive at this action from navigating the link on the  “Search Fundamentals” action.

Request Format

Attributes

Attribute
Description
Type
Required?
Default
Notes
idThe ID of the filing.StringYes

Response

Returns a filing resource if there are no errors. It will return an error if the request fails.

Example Request/Response

Get Filing Example

Back To Top

Resources

Fundamental

Definition

Fundamental resources represent a list of fundamental values. When a fundamental is returned from an action, regardless if it’s a single fundamental tag or multiple fundamentals being returned,  it will always be wrapped within a fundamentals collection.

Attributes

Attribute
Type
Description
idStringTag's ID.
tagStringThe Fundamental tag. Please see Fundamental Tag Definitions for more information.
valueIntegerThe standardized value of the tag.
fiscal_yearIntegerThe fiscal year of the data.
fiscal_quarterIntegerThe fiscal quarter of the data.
start_periodDateThe start date of the period. Applies only to tags with duration types.
end_periodDateThe end date of the period.
tagsListList of fundamental values which belong to this period. Please see the Fundamental Tag Definition.
linksHypermedia AffordanceContains IDs to the tag's parent filing and company. These IDs are used to fill the top-level link templates.

Back To Top

Fundamental Tag

Definition

Fundamental tag resources represent a  fundamental value. When a fundamental is returned from an action, regardless if it’s a single fundamental value or multiple fundamentals being returned,  it will always be wrapped within a tags collection.

Attributes

Attribute
Type
Description
idStringTag's ID.
tagStringThe Fundamental tag. Please see Fundamental Tag Definitions for more information.
valueIntegerThe standardized value of the tag.
transparenciesListList of source transparency values. Please see the Fundamental Tag Transparency Definition.

Back To Top

Fundamental Transparency

Definition

Fundamental tag transparency resources represent a fundamental tag’s source transparency information.

Attributes

Attribute
Type
Description
nameStringThe name of the transparency item.
operatorStringOperator which is used with the other source transparency items to compute the value of the parent tag.
Operator values can be either a '-', '+', '*', or '/'.
valueIntegerSource transparency item's value.
domainStringThe transparency item's XBRL domain. If the item does not belong to a specific XBRL domain its value will be null.
sourceStringThe source of the transparency item. Source values can be xbrl_usgaap, xbrl_extension or tagnifi_fundamentals (for calculated tags).

Back To Top

Company

Definition

Company resources represents a company within the TagniFi API. When a company is returned from an action, regardless if it’s a single company or multiple companies being returned,  it will always be wrapped within a companies collection.

Attributes

Attribute
Type
Description
idStringCompany's ID.
nameStringCompany's name.
sic_codeIntegerCompany's self-reported SIC code.
web_siteUrlCompany's web site.
tickerStringCompany's latest ticker symbol.

Back To Top

Filing

Definition

Filing resources represents a filing within the TagniFi API. When a filing is returned from an action, regardless if it’s a single filing or multiple filings being returned,  it will always be wrapped within a filings collection.

Attributes

Attribute
Type
Description
idStringFiling's ID.
typeStringType of the filing. (ex. 10-K, 10-Q, 10-K/A, or 10-Q/A)
html_linkUrlLink to the html version of the filing.
dateDateDate in which the filing was submitted.
linksHypermedia AffordanceContains a link to the filing's company.

Back To Top