Filings API API Reference

Overview

This document is the complete reference for the Context Analytics Filings API. It covers authentication, all available endpoints, request parameters, and response codes — everything you need to integrate filing document processing into your application.

The API lets you programmatically upload, process, and query SEC filing documents. Once a document is uploaded, Context Analytics extracts structured data including a summary, full content, and tables — all accessible via a single HTTP POST endpoint.

Base URL
https://api-fillings.socialmarketanalytics.com/api/fillings

How it works

Every request follows the same pattern — POST to the base URL with ontology=fillings and an items value that selects the operation:

items valueWhat it does
file_uploadSubmit a filing document for processing. Returns a tracking_code.
file_trackPoll processing status and retrieve extracted content using the tracking code.
post_commentAttach a review comment to a tracked filing.
track_commentRetrieve the latest comment on a tracked filing.
reprocessedList all filings reprocessed and published in the last 24 hours.

Typical workflow: file_upload → poll file_track until status returns completed (or fail) → annotate via post_comment.


Authentication

All requests require a valid api_key sent as a POST field. Keys are issued per subscription — contact support to obtain yours.

  • Must be sent via POST — not a query string or header.
  • All requests must use HTTPS. Plain HTTP will return error 1003.
  • An invalid or missing key returns error 1012 or 1011 respectively.

Example request (cURL)
curl -X POST "https://api-fillings.socialmarketanalytics.com/api/fillings" \
  -F "api_key=[API KEY]" \
  -F "ontology=fillings" \
  -F "items=file_upload"

Response Codes

Every API response includes an HTTP status code along with an optional numeric code and message in the body. Review each section below to understand what to expect.

SUCCESS

200 OK

The request was successful.


AUTHENTICATION

1000 Authentication Fail

Authentication error.

1001 Forbidden

Forbidden access.

1002 API access suspended

Please contact support for instructions on how to gain access privileges.

1003 Unsecure connection

API requests must use HTTPS.

1004 Invalid API call

API key must be sent via POST method.

1011 Missing API Key

api_key is required.

1012 Invalid API Key

API key is not recognized. Please verify your API key.


API ERROR CODES

4001 Invalid file type

File type is not supported. Accepted: html, htm, pdf, txt, mht.

4002 Invalid document date

Invalid document date. Valid format: MMM-DD-YYYY (e.g. Jul-24-2019).

4003 Invalid document id

Document id should be alphanumeric.

4004 Missing tracking code

Tracking code is required for file_track, post_comment, and track_comment.

4005 Invalid tracking code

The provided tracking code is not valid.

4006 Missing document date

Document date is required for file_upload.

4007 Missing document id

Document id is required for file_upload.

4008 Missing document type

Document type is required for file_upload.

4009 Missing company name

Company name is required for file_upload.

4010 Missing comment

Comment is required for post_comment.

4011 Missing company id

Company id is required.

4012 No Reprocessed Files

No reprocessed files found.


SERVER ERRORS

400 Bad Request

The request was invalid or could not be understood by the server.

500 Internal Server Error

The server encountered an error while processing your request.

502 Gateway Error

The load balancer or web server had trouble connecting. Please try again.

503 Service Unavailable

The service is temporarily unavailable. Please try again.

End Points

post File Upload

Submits a filing document for processing. On success, returns a unique tracking_code to monitor progress.

Accepted file formats: html, htm, pdf, txt, mht. Date format: MMM-DD-YYYY (e.g. Aug-24-2019).

Body Params

api_key:
required
 string

A verification key required to identify subscription access. Must be sent via POST.
ontology:
required
 string

Set to fillings.
items:
required
 string

Set to file_upload.
document_id:
required
 string

Unique identifier for the document (alphanumeric).
company_name:
required
 string

Name of the company that filed the document.
document_date:
required
 string

Filing date. Format: MMM-DD-YYYY (e.g. Jul-24-2019).
document_type:
required
 string

Filing form type. Accepted: 10-K, 10-Q, 8-K, 20-F, 6-K, 40-F, S-1 and variants.
file:
required
 file

The source document to upload (multipart/form-data).
doc_format:
required
 integer

Numeric code for the file format. Common values: 1 = TXT, 2 = HTML, 3 = PDF, 28 = MHT.
company_id:
optional
 string

Internal company identifier.
edgar_link:
optional
 string

URL to the filing on SEC EDGAR.
language:
optional
 string

Language code of the document (max 20 chars, e.g. en-US).
countrycode:
optional
 string

Country of origin (max 15 chars, e.g. US).

Examples


<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-fillings.socialmarketanalytics.com/api/fillings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array(
      'api_key' => '[API KEY]',
      'items' => 'file_upload',
      'ontology' => 'fillings',
      'document_id' => '2143743042',
      'company_name' => 'Test_company',
      'document_date' => 'Aug-24-2019',
      'document_type' => '10-Q/A',
      'doc_format' => 2,
      'file' => new CURLFILE('/path/to/file')
    ),
  CURLOPT_HTTPHEADER => array(
    "content-type: multipart/form-data"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api-fillings.socialmarketanalytics.com/api/fillings")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/x-www-form-urlencoded'
form_data=  [['api_key', '[API KEY]'],['items', 'file_upload'],['ontology', 'fillings'],['document_id', '2143743042'],['company_name', 'Test_company'],['document_date', 'Aug-24-2019'],['document_type', '10-Q/A'],['doc_format', 2],['file', File.open('/path/to/file')]]
request.set_form form_data, 'multipart/form-data'

response = https.request(request)
puts response.read_body

import requests

url = "https://api-fillings.socialmarketanalytics.com/api/fillings"

payload =  {
    'api_key': '[API KEY]',
     'items': 'file_upload',
     'ontology': 'fillings',
     'document_id': '2143743042',
     'company_name': 'Test_company',
     'document_date': 'Aug-24-2019',
     'document_type': '10-Q/A',
     'doc_format': 2
}
files= [
    ('file', open('/path/to/file','rb'))
]
headers = {
    'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, data=payload, headers=headers, files=files)

print(response.text.encode('utf8'))
var client = new RestClient("https://api-fillings.socialmarketanalytics.com/api/fillings");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "multipart/form-data");
request.AddParameter("api_key", "[API KEY]");
request.AddParameter("items", "file_upload");
request.AddParameter("ontology", "fillings");
request.AddParameter("document_id", "2143743042");
request.AddParameter("company_name", "Test_company");
request.AddParameter("document_date", "Aug-24-2019");
request.AddParameter("document_type", "10-Q/A");
request.AddParameter("doc_format", "2");
request.AddFile("file", "/path/to/file");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

post File Track

Returns the processing status and output data for a previously uploaded filing. Poll this endpoint after upload until status is completed or fail.

Use the component param to control which sections are returned (default: summary,content). Available components: summary, content, tables.

Body Params

api_key:
required
 string

A verification key required to identify subscription access.
ontology:
required
 string

Set to fillings.
items:
required
 string

Set to file_track.
tracking_code:
required
 string

The tracking token returned by a successful file_upload call.
component:
optional
 string

Comma-separated list of response sections to include. Default: summary,content. Available options: summary, content, tables.
type:
optional
 string

Set to sma to apply SMA content parsing on the response.
get_index:
optional
 string

Extract a specific section from content. For example: P1 (Part 1), P1:i1&i2 (specific items), S (Signatures), N (Notes), O (Others).

Examples

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-fillings.socialmarketanalytics.com/api/fillings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array(
      'api_key' => '[API KEY]',
      'items' => 'file_track',
      'ontology' => 'fillings',
      'tracking_code' => '[TRACKING CODE]'
    ),
  CURLOPT_HTTPHEADER => array(
    "content-type: multipart/form-data"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
require 'uri'
require 'net/http'

url = URI("https://api-fillings.socialmarketanalytics.com/api/fillings")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/x-www-form-urlencoded'
form_data=  [['api_key', '[API KEY]'],['items', 'file_track'],['ontology', 'fillings'],['tracking_code', '[TRACKING CODE]']]
request.set_form form_data, 'multipart/form-data'

response = https.request(request)
puts response.read_body
import requests

url = "https://api-fillings.socialmarketanalytics.com/api/fillings"

payload =  {
     'api_key': '[API KEY]',
     'items': 'file_track',
     'ontology': 'fillings',
     'tracking_code': '[TRACKING CODE]'
}

headers = {
    'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text.encode('utf8'))
var client = new RestClient("https://api-fillings.socialmarketanalytics.com/api/fillings");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "multipart/form-data");
request.AddParameter("api_key", "[API KEY]");
request.AddParameter("items", "file_track");
request.AddParameter("ontology", "fillings");
request.AddParameter("tracking_code", "[TRACKING CODE]");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

post Post Comment

Attaches a comment to a tracked filing using its tracking code.

Body Params

api_key:
required
 string

A verification key required to identify subscription access.
ontology:
required
 string

Set to fillings.
items:
required
 string

Set to post_comment.
tracking_code:
required
 string

Tracking token of the target filing.
comment:
required
 string

The comment text to attach to the filing.

Examples

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-fillings.socialmarketanalytics.com/api/fillings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array(
    'api_key' => '[API KEY]',
    'ontology' => 'fillings',
    'items' => 'post_comment',
    'tracking_code' => '[TRACKING CODE]',
    'comment' => 'Review complete, approved.'
  ),
  CURLOPT_HTTPHEADER => array("Content-Type: application/x-www-form-urlencoded"),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) { echo "cURL Error #:" . $err; } else { echo $response; }
require 'uri'
require 'net/http'

url = URI("https://api-fillings.socialmarketanalytics.com/api/fillings")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
form_data = [['api_key', '[API KEY]'],['ontology', 'fillings'],['items', 'post_comment'],['tracking_code', '[TRACKING CODE]'],['comment', 'Review complete, approved.']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body
import requests

url = "https://api-fillings.socialmarketanalytics.com/api/fillings"
payload = {
  'api_key': '[API KEY]',
  'ontology': 'fillings',
  'items': 'post_comment',
  'tracking_code': '[TRACKING CODE]',
  'comment': 'Review complete, approved.'
}
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text.encode('utf8'))
var client = new RestClient("https://api-fillings.socialmarketanalytics.com/api/fillings");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "multipart/form-data");
request.AddParameter("api_key", "[API KEY]");
request.AddParameter("ontology", "fillings");
request.AddParameter("items", "post_comment");
request.AddParameter("tracking_code", "[TRACKING CODE]");
request.AddParameter("comment", "Review complete, approved.");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

post Track Comment

Retrieves the most recent comment posted against a filing tracking code.

Body Params

api_key:
required
 string

A verification key required to identify subscription access.
ontology:
required
 string

Set to fillings.
items:
required
 string

Set to track_comment.
tracking_code:
required
 string

The tracking token of the filing whose comment you want to retrieve.

Examples

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-fillings.socialmarketanalytics.com/api/fillings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array(
    'api_key' => '[API KEY]',
    'ontology' => 'fillings',
    'items' => 'track_comment',
    'tracking_code' => '[TRACKING CODE]'
  ),
  CURLOPT_HTTPHEADER => array("content-type: multipart/form-data"),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
require 'uri'
require 'net/http'

url = URI("https://api-fillings.socialmarketanalytics.com/api/fillings")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
form_data = [['api_key', '[API KEY]'],['ontology', 'fillings'],['items', 'track_comment'],['tracking_code', '[TRACKING CODE]']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body
import requests

url = "https://api-fillings.socialmarketanalytics.com/api/fillings"
payload = {
  'api_key': '[API KEY]',
  'ontology': 'fillings',
  'items': 'track_comment',
  'tracking_code': '[TRACKING CODE]'
}
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text.encode('utf8'))
var client = new RestClient("https://api-fillings.socialmarketanalytics.com/api/fillings");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "multipart/form-data");
request.AddParameter("api_key", "[API KEY]");
request.AddParameter("ontology", "fillings");
request.AddParameter("items", "track_comment");
request.AddParameter("tracking_code", "[TRACKING CODE]");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

post Reprocessed

Returns the list of filing documents that have been reprocessed and published successfully within the last 24 hours.

Body Params

api_key:
required
 string

A verification key required to identify subscription access.
ontology:
required
 string

Set to fillings.
items:
required
 string

Set to reprocessed.

Examples

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-fillings.socialmarketanalytics.com/api/fillings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array(
    'api_key' => '[API KEY]',
    'ontology' => 'fillings',
    'items' => 'reprocessed'
  ),
  CURLOPT_HTTPHEADER => array("content-type: multipart/form-data"),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
require 'uri'
require 'net/http'

url = URI("https://api-fillings.socialmarketanalytics.com/api/fillings")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
form_data = [['api_key', '[API KEY]'],['ontology', 'fillings'],['items', 'reprocessed']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body
import requests

url = "https://api-fillings.socialmarketanalytics.com/api/fillings"
payload = {
  'api_key': '[API KEY]',
  'ontology': 'fillings',
  'items': 'reprocessed'
}
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text.encode('utf8'))
var client = new RestClient("https://api-fillings.socialmarketanalytics.com/api/fillings");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "multipart/form-data");
request.AddParameter("api_key", "[API KEY]");
request.AddParameter("ontology", "fillings");
request.AddParameter("items", "reprocessed");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);