Securities and Exchange Commission (SEC)

As the name suggests, the endpoints in this section pertain to data from the Securities and Exchange Commission (SEC). Parsed data is available for the most popular and significant form types in the SEC.

Introduction

The APIs in this section provide historical data access through queries and real-time data streaming through subscription connections. For details about the request and response structures, reference the respective GraphQL documentation for that form type in the GraphQL Documentation section.

GraphQL queries require the API key to be set in the headers of each request and subscriptions require them to be set with an initial payload in the connection_init websocket message. For examples of queries and subscriptions, checkout the Quickstart section.

Additionally, user's can learn the various endpoints and test the APIs in the GraphQL playground. To get to the playground pertaining to the data you want, please reference the Playground section.

Pagination

All query endpoints have a total.value attribute which can be used to obtain the number of available records for a specific query. This value can then be used as a reference to increment your offset until all possible values have been received, determined with the final response not containing any records.

Query results are limited to 10 records per page and subscription results are broadcast to clients as they become available and so pagination does not apply to subscription endpoints.

Filtering

Our API uses Apache Lucene syntax to filter for documents against an ElasticSearch backend. All attributes within the data attribute of an endpoint supports the full scope of the query engine and can be filtered on.

The data attribute represents the root of the document. For example, filtering for a filing with a specific accession number in the form_4 endpoint can be done with the query:

# Write your query or mutation here
query {
    form_4 (offset: 20, query: "filing_accession_number: * AND filing_report_date: [2014-01-01 TO 2022-01-01] AND document_data.issuer: *"){
        took,
        data{
            filing_report_date,
            filing_accession_number,
            document_data{
                issuer{
                    name
                }
            }
        }
    }
}

Query endpoints also offer an aggregation (aggs) attribute to create aggregations that can be used to answer questions such as "What are the Top 10 holdings of a specific stock among portfolio managers" as determined in form 13F-HR (form_13fhr) filings.

To learn more about how to use aggregations see ElasticSearch Aggregations

We offer the full-flexibility of our system to clients. This means that it is possible for users to create complex queries with long execution times. Aggregations can cause this. In order to protect our systems from abuse, all queries will timeout after 5 seconds of execution.

Important Considerations

All subscriptions must send a keep-alive message to our servers or the connection is at risk of being closed if it is idle for more than an hour. We recommend an interval of once every minute (60s).

For a full list of possible errors that can be returned and what they mean, check out the Errors section.

Additionally, it is also important to note that some filing form types like insider transactions may show duplicated data due to a filing being generated for both the issuer entity and the transacting entity. In general, it is best to filter for data in a specific filing in all form types by filtering for both the entity_cik and filing_accession_number which should be available in nearly all the endpoints. When filtering for all data pertaining for a specific entity, the entity_cik attribute alone can be used. Generally, filtering only by the filing_accession_number attribute should be avoided in filings that reference more than 1 entity in order to prevent duplicate values from showing up in your results.

To understand what the attributes of certain endpoints mean, you can reference the SEC XML Specifications for the specific form type and the actual published document to determine the attributes of interest in the endpoints.

GraphQL Playground

This section contains the links to GraphQL playgrounds that can be used for testing, understanding the documentation, and structuring queries and subscriptions for your services. To authenticate your requests, please insert {"api-key": "<YOUR API KEY>"} in the HTTP Headers section on the bottom.

SEC API

This API contains all information regarding data from the SEC.

GraphQL Documentation

Errors

Whenever a request is unsuccessful, FactIQ will return an error response with an error code and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

GraphQL Query Error Codes

{
    "data": null,
    "extensions": {
        "request-id": "e5a32713-5022-4aec-9312-9a70b7099d42"
    },
    "errors": [
        {
            "message": "Invalid credentials. Make sure you are using a valid api key.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": [
                "filing"
            ],
            "extensions": {
                "code": "api/invalid-credentials-error"
            }
        }
    ]
}

GraphQL Subscription Error Codes

{
    "data": null,
    "errors": [
        {
            "message": "Invalid credentials. Make sure you are using a valid api key.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": [
                "filing"
            ],
            "extensions": {
                "code": "api/invalid-credentials-error"
            }
        }
    ]
}