Fincoded
 Log In Sign Up

Fincoded API Introduction

Getting set up and started with the API

Jump to: Get Started Base URL Authentication Response Model Filtering Pagination Cursor Sorting Formatting Rate Limits Libraries

The Fincoded API provides developers with an easy-to-use programmatic interface for accessing a wide range of financial data sourced from SEC filings. This document guides you through the process of integrating Fincoded with your applications using our RESTful API.

Get Started

Before you start making API requests, you will need to obtain an API key. This key is required to authenticate your requests and ensure proper access to our data resources. To obtain your API key, please visit the pricing page and sign up for a free trial account or no-commitment paid plan.

Base URL

All API requests should be made to the following base URL. Each data set is queried via a different path at the end of the URL. See the individual data set documentation pages to obtain each URL.

https://api.fincoded.com/v1/[dataset]

Authentication

To authenticate your API requests, include the key query string parameter with your API key in every request, as shown below:

https://api.fincoded.com/v1/[dataset]?key=[YOUR_API_KEY]

Replace [YOUR_API_KEY] with the API key you received upon registration, which is also available at any time on your account dashboard.

Please note For the sake of readability, the key parameter will not be included in example API URLs below and on other API documentation pages, but must always be included when you make your requests.

Response Data Model

Response type: JSON

Unless otherwise stated in the documentation for an API endpoint, all API responses are in JSON syntax, with the following basic response structure:

{
    "data": results[],   // The data set results
    "metadata": {
        "count":  number  // Number of results in this response
        "total":  number  // Total number of available results for the request, across all pages
        "page":   number  // Page number of results
        "pages":  number  // Number of pages available
        "cursor": string  // A watermark you can filter on to get new data, or anchor pagination
    }
}

The data model for the results of each endpoint is different, and is described in the documentation page for each endpoint. Note that for data extracted from XML-based SEC filings (like Form D and NPORT-P), the JSON data model for each of these has been designed to resemble the structure of the original XML as closely as possible.

Each item of data that has been extracted from an SEC filing will have a sourceReference object that specifies the provenance (original filing details) of the data.

Filtering

You can use query string parameters to filter data based on the properties of each data set's JSON structure. The structure of each data set, and therefore the properties available for filtering, is explained on the individual API documentation page for each end point.

You can perform a variety of comparisons using the following operators: =, <=, >=, !=, <, and >.

Query Syntax

To query data, append one or more query string parameters to the endpoint URL with the desired operators. The general syntax is as follows:

https://api.fincoded.com/v1/[dataset]?property[operator]value

Replace property with the full dotted path name of the JSON object property you want to filter on, [operator] with the comparison operator, and value with the value you want to compare against.

Supported Operators
  • =: Equal to
  • <=: Less than or equal to
  • >=: Greater than or equal to
  • !=: Not equal to
  • <: Less than
  • >: Greater than
Multiple Value Comparisons

For the = and != operators, you can comma-separate multiple values in the comparison syntax to filter results that contain any of the specified values when you use =, or none of the specified values when you use !=

For example, API query strings with:

  • ?investmentFund.type=HedgeFund,PrivateEquity: Will return data where the investmentFund.type field of the data set has a value of either HedgeFund or PrivateEquity.
  • ?investmentFund.type!=HedgeFund,PrivateEquity: Will return data where the investmentFund.type field of the data set has a value of anything except HedgeFund or PrivateEquity.

As an alternative syntax, you can also specify multiple value comparisons by filtering on the same property name multiple times, e.g.

  • ?investmentFund.type=HedgeFund&investmentFund.type=PrivateEquity: The same as the first example above.
  • ?investmentFund.type!=HedgeFund&investmentFund.type!=PrivateEquity: The same as the second example above.

Date Comparisons

For date comparisons, you typically specify operator comparison values in the YYYY-MM-DD syntax, e.g. 2023-03-31. The API automatically assumes the start or end of this day depending on the operator. For example, if you specify "Less than" 2023-03-31, the API will assume the start of the day, so that you only receive results for 2023-03-30 and earlier. But if you specify "Less than or equal to" 2023-03-31, the API will assume the end of the day, so that you receive results that include any time on 2023-03-31. You can override this behaviour by specifying your operator value in the full date-time syntax, e.g. 2023-04-10T00:00:00Z.

Property Exists / Has Value Comparisons

To filter documents by a non-empty property value – i.e. the property must have any value, but not null/empty – use the special asterisk syntax of the equal operator: property=*

Sub-Document Comparisons

Some of the API endpoints include arrays of sub-documents as part of each item of data, for example the informationTable of holdings in a 13F or the nonDerivativeTable of transactions in a Form 4. These arrays of sub-documents (aka objects) are identified in the API documentation Response Data Model schemas as having a type of object[].

By default, when you filter by multiple properties in a sub-document, the API will assume that these conditions should all match the same sub-document. For example, if you filter 13F data by informationTable.cusip=XXXXX and informationTable.putOrCall=put, the API will return 13F data where the same sub-document in the informationTable array matches both of those conditions: a cusip of XXXXX and a putOrCall of put.

If you don't want this behaviour, prefix the path of the filter with a caret ^ character, e.g. filtering by ^informationTable.cusip=XXXXX and ^informationTable.putOrCall=put will match 13Fs where any informationTable entry has cusip=XXXXX and any other informationTable entry (not necessarily the same one) has a putOrCall of put.

Filter Examples

These examples are for the demonstration of filter query string syntax only, and do not constitute actual working queries.

  1. To fetch all resources with a offering.totalPrice numeric field equal to exactly 100,000, use the following request:

https://api.fincoded.com/v1/[dataset]?offering.totalPrice=100000

  1. To fetch resources with a numOfficers numeric field greater than 3, use:

https://api.fincoded.com/v1/[dataset]?numOfficers>3

  1. To fetch resources with a transactions.derivativeTable.exerciseDate date field less than or equal to 2023-01-01 (i.e. that also include any time on 2023-01-01), use:

https://api.fincoded.com/v1/[dataset]?transactions.derivativeTable.exerciseDate<=2023-01-01

  1. To fetch resources with a status.draft boolean field not equal to true, use:

https://api.fincoded.com/v1/[dataset]?status.draft!=true

  1. To fetch resources with a issuer.industryType string field equal to either Retail or Utilities, and a transactionDate date field greater than 2022-09-21, use:

https://api.fincoded.com/v1/[dataset]?issuer.industryType=Retail,Utilities&transactionDate>2022-09-21

Filtering Sub-Document Results

If you try the above exampels, you'll see that the full document is returned that matches each query. For example, if you query institutional (13F-HR) data by informationTable.cusip=XXXXX, then the results will contain the full 13F records that mention that CUSIP somewhere in their holdings, including every other holding, i.e. every other informationTable result is also returned, not just the matching entry.

If you want to filter the sub-documents in the returned data to only include matching results – in this example, only those that match the queried CUSIP – then add the subdocuments=true parameter to the API call. In this example, the informationTable array of each returned 13F data record will then only contain the holdings that match the queried CUSIP.

Cursor

When you paginate, new data records can "move" the pages around. For example, if you are requesting page 2 and new data records have been created since you requested page 1, then some of the original page 1 results will be "pushed" on to page 2, giving you some data that duplicates what you received in the original page 1 request.

To avoid this problem, you can anchor subsequent pagination requests at page 1 of results. To do this, get the metadata.cursor watermark value from the page 1 results and then pass in an additional filter for subsequent pages, in the format &cursor<=XXXXXXXXXXXXXXXXXXXXXXX

Similarly, when requesting new data, you often want to request anything new since your last request. You can use the cursor to solve this issue, again by passing it in as an additional filter parameter, in the format &cursor>XXXXXXXXXXXXXXXXXXXXXXX, where XXXXXXXXXXXXXXXXXXXXXXX is the watermark from your most recent set of results.

Sorting

You can sort the results using the sortBy and sortOrder query string parameters.

  • sortBy: The field you want to sort the results by, in full dotted JSON path syntax.
  • sortOrder: The order in which you want to sort the results. Accepted values are asc for ascending order and desc for descending order.

For example:

https://api.fincoded.com/v1/[dataset]?sortBy=name&sortOrder=asc

Formatting

The API purposefully serves data that closely resembles the original filing data as much as possible, where the data has been extracted directly from a filing. However, we also recognize that some developers want to integrate API calls directly into their applications and display the response data in a more user-friendly format without adding custom code.

For these situations, the API supports a format parameter that transforms parts of the output data for more user-friendly consumption. You can use any combination of these values, comma separated in the format parameter, to transform parts of the API response data:

  • numc: Number commas. All number or number[] type fields will be converted to strings, and formatted with commas.
  • numu: Numer units. All number or number[] type fields will be converted to strings, and formatted with M (millions), B (billions) or T (trillions) suffixes where relevant, to one decimal place. If combined with numc, only values under one million will be formatted with commas.
  • exps: Expand state codes. All properties that contain SEC state/country codes will be expanded into the full state/country name.

For example:

https://api.fincoded.com/v1/form-d?offeringData.industryGroup.type=Investing&format=numc,numu,exps

Rate Limits

Please note that Fincoded enforces rate limits on API requests. The default rate limit is 100,000 requests per day for professional users and 20 per day for free trial users. If you exceed the rate limit, you will receive an HTTP 429 (Too Many Requests) response.

You can view your usage in a given window at any point on your user dashboard. You can also retrieve your rate limit usage programmatically using the HTTP response headers of every API request.

Libraries

Over the years, REST APIs – like the Fincoded API – have become the industry standard for web service development due to their simplicity, scalability, and ease of use. You can even use command-line tools like CURL to query the API.

You can use any standard HTTP library to simplify the querying and parsing of API responses. Popular libraries include:

Support

If you need assistance or have questions, please email us at support@fincoded.com