API Documentation

Power your applications with FilingReader's comprehensive API

Base URL: https://api.filingreader.com

Introduction

Welcome to FilingReader's API! This guide will help you quickly get started with accessing stock exchange filings, company information, and financial news through our API.

Getting Started

Obtain Your API Key
Every request to the API requires an API key. You can view our API plans and generate a free trial API key.
Make Your First Request
Once you have your API key, try a simple test request:
```
curl -H "X-API-KEY: your_api_key" https://api.filingreader.com/health
```

Authentication

Include your API key in the X-API-KEY header with every request:

curl -H "X-API-KEY: your_api_key" https://api.filingreader.com/v1/companies

If you receive a 401 Unauthorized error, double-check that:

Your API key is correct
Your API key is active
You've included the header properly

API Plans

We offer different API plans to meet your needs:

Feature	Trial	Basic	Premium
Results per page	Up to 5	Up to 20	Up to 100
Requests per hour	10	1,000	10,000
Downloads per day	5	3,000	Unlimited
Historical data	1 year	5 years	Full archive

Contact info@filingreader.com to upgrade your plan.

Core Endpoints

Available Endpoints

Company Endpoints

GET /v1/companies - List companies
GET /v1/companies/exchange/:exchangeCode - List companies for a specific exchange
GET /v1/companies/:stockCode - Get company by stock code

Filing Endpoints

GET /v1/filings - List filings
GET /v1/filings/exchange/:exchangeCode - List filings for a specific exchange
GET /v1/filings/exchange/:exchangeCode/filing-type/:typeName - List filings for a specific exchange filtered by type
GET /v1/filings/company/:stockCode - List filings for a specific company
GET /v1/filings/company/:stockCode/filing-type/:typeName - List filings for a specific company filtered by type
GET /v1/filings/:bulletinId - Get filing details by bulletin ID
GET /v1/filings/:bulletinId/download - Get filing download URL

Filing Type Endpoints

GET /v1/filing-types - List all filing types
GET /v1/filings/filing-type/:typeName - Filter filings by type name

News Endpoints

GET /v1/news - List news stories
GET /v1/news/id/:id - Get news story
GET /v1/news/company/:stockCode - Get company news

Company Endpoints

GET/v1/companies

List companies with filters and pagination

Parameters:

name(string)

Search by company name

sector(string)

Filter by business sector

page(integer)

Page number (default: 1)

limit(integer)

Results per page (default: 20, maximum depends on your plan)

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/companies"

Example Response:

{
  "status": "success",
  "data": [
    {
      "name": {
        "en": "Bank of China",
        "zh": "中国银行"
      },
      "stockCode": "HKEX:0001",
      "sector": "Financial Services",
      "country": "CN"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 42
  }
}

GET/v1/companies/exchange/:exchangeCode

List companies from a specific exchange

Parameters:

exchangeCode(string)required

Exchange code (e.g., HKEX, SSE, SZSE, BSE, NSE, SET, JSE, TSE, NZX, IDX, LSE, OSL)

name(string)

Search by company name

sector(string)

Filter by business sector

region(string)

Filter by region/country

page(integer)

Page number (default: 1)

limit(integer)

Results per page (default: 20, maximum depends on your plan)

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/companies/exchange/exampleexchangeCode"

Example Response:

{
  "status": "success",
  "data": [
    {
      "name": {
        "en": "Bank of China",
        "zh": "中国银行"
      },
      "stockCode": "HKEX:0001",
      "sector": "Financial Services",
      "country": "CN"
    },
    {
      "name": {
        "en": "China Construction Bank",
        "zh": "中国建设银行"
      },
      "stockCode": "HKEX:0939",
      "sector": "Financial Services",
      "country": "CN"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 3,
    "totalItems": 54
  }
}

GET/v1/companies/:stockCode

Get details for a specific company by stock code

Parameters:

stockCode(string)required

Stock code including exchange prefix (e.g., HKEX:0001)

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/companies/examplestockCode"

Example Response:

{
  "status": "success",
  "data": {
    "id": "c789",
    "name": {
      "en": "Bank of China",
      "zh": "中国银行"
    },
    "stockCodes": [
      "HKEX:0001",
      "SSE:601988"
    ],
    "exchanges": [
      "HKEX",
      "SSE"
    ],
    "country": "CN",
    "sector": "Financial Services"
  }
}

Filing Endpoints

GET/v1/filings

List filings with filters and pagination

Parameters:

keyword(string)

Search by keyword in filing content

startDate(string)

Start date (YYYY-MM-DD)

endDate(string)

End date (YYYY-MM-DD)

page(integer)

Page number

limit(integer)

Results per page

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings"

Example Response:

{
  "status": "success",
  "data": [
    {
      "title": "2024 Annual Report",
      "company": "Bank of China",
      "stockCode": "HKEX:0001",
      "exchange": "HKEX",
      "filingDate": "2024-03-20",
      "language": "en",
      "filingTypes": [
        {
          "id": 1,
          "name": "annual",
          "description": "Annual financial reports including Chinese 年度报告"
        }
      ],
      "url": "https://api.filingreader.com/v1/filings/BULL12345/download"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 50,
    "totalItems": 998
  }
}

GET/v1/filings/exchange/:exchangeCode

List filings for a specific exchange

Parameters:

exchangeCode(string)required

Exchange code (e.g., HKEX, SSE, SZSE, BSE, NSE, SET, JSE, TSE, NZX, IDX, LSE, OSL)

keyword(string)

Search by keyword in filing content

startDate(string)

Start date (YYYY-MM-DD)

endDate(string)

End date (YYYY-MM-DD)

page(integer)

Page number

limit(integer)

Results per page

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/exchange/exampleexchangeCode"

Example Response:

{
  "status": "success",
  "data": [
    {
      "title": "2024 Annual Report",
      "company": "Bank of China",
      "stockCode": "HKEX:0001",
      "exchange": "HKEX",
      "filingDate": "2024-03-20",
      "language": "en",
      "filingTypes": [
        {
          "id": 1,
          "name": "annual",
          "description": "Annual financial reports including Chinese 年度报告"
        }
      ],
      "url": "https://api.filingreader.com/v1/filings/BULL12345/download"
    },
    {
      "title": "Q1 2024 Results Announcement",
      "company": "China Construction Bank",
      "stockCode": "HKEX:0939",
      "exchange": "HKEX",
      "filingDate": "2024-04-15",
      "language": "en",
      "filingTypes": [
        {
          "id": 3,
          "name": "quarterly",
          "description": "Quarterly financial reports (季度报告)"
        }
      ],
      "url": "https://api.filingreader.com/v1/filings/BULL54321/download"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 25,
    "totalItems": 487
  }
}

GET/v1/filings/:bulletinId

Get details for a specific filing by bulletin ID

Parameters:

bulletinId(string)required

Bulletin ID of the filing

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/examplebulletinId"

Example Response:

{
  "status": "success",
  "data": {
    "bulletinId": "BULL12345",
    "title": "2024 Annual Report",
    "company": "Bank of China",
    "stockCode": "HKEX:0001",
    "exchange": "HKEX",
    "filingDate": "2024-03-20",
    "publishDate": "2024-03-20",
    "language": "en",
    "fileType": "PDF",
    "fileSize": 2457891,
    "filingTypes": [
      {
        "id": 1,
        "name": "annual",
        "description": "Annual financial reports including Chinese 年度报告"
      }
    ],
    "fileInfo": {
      "fileSize": 2457891,
      "pageCount": 35,
      "hasText": true,
      "isScanned": false,
      "isBroken": false
    }
  }
}

GET/v1/filings/:bulletinId/download

Get a secure download URL for a filing

Parameters:

bulletinId(string)required

Bulletin ID of the filing

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/examplebulletinId/download"

Example Response:

{
  "status": "success",
  "data": {
    "url": "https://filingreader-public.s3.ap-east-1.amazonaws.com/filings/f12345.pdf?signature=abc123...",
    "expiresAt": "2024-03-24T14:35:00Z"
  }
}

GET/v1/filings/company/:stockCode

Get filings for a specific company by stock code

Parameters:

stockCode(string)required

Stock code (e.g., HKEX:0001)

startDate(string)

Start date (YYYY-MM-DD)

endDate(string)

End date (YYYY-MM-DD)

keyword(string)

Search by keyword in filing content

page(integer)

Page number

limit(integer)

Results per page

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/company/examplestockCode"

Example Response:

{
  "status": "success",
  "data": [
    {
      "bulletinId": "BULL12345",
      "title": "2024 Annual Report",
      "stockCode": "HKEX:0001",
      "timestamp": "2024-03-20T10:30:00Z",
      "createdDate": "2024-03-20",
      "filingTypes": [
        {
          "id": 1,
          "name": "annual",
          "description": "Annual financial reports including Chinese 年度报告"
        }
      ],
      "fileInfo": {
        "fileSize": 2457891,
        "pageCount": 35,
        "hasText": true,
        "isScanned": false,
        "isBroken": false
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 3,
    "totalItems": 28
  }
}

Filing Type Endpoints

GET/v1/filing-types

List all available filing types for filtering filings

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filing-types"

Example Response:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "annual",
      "description": "Annual financial reports including Chinese 年度报告"
    },
    {
      "id": 2,
      "name": "interim",
      "description": "Half-year financial reports (半年度报告)"
    },
    {
      "id": 3,
      "name": "quarterly",
      "description": "Quarterly financial reports (季度报告)"
    }
  ]
}

GET/v1/filings/filing-type/:typeName

Filter filings by a specific filing type name (e.g., 'annual', 'interim')

Parameters:

typeName(string)required

Name of the filing type (e.g., 'annual', 'interim', 'quarterly')

page(integer)

Page number (default: 1)

limit(integer)

Results per page (default: 20, maximum depends on your plan)

startDate(string)

Start date (YYYY-MM-DD)

endDate(string)

End date (YYYY-MM-DD)

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/filing-type/exampletypeName"

Example Response:

{
  "status": "success",
  "data": [
    {
      "title": "2024 Annual Report",
      "company": "Bank of China",
      "stockCode": "HKEX:0001",
      "exchange": "HKEX",
      "filingDate": "2024-03-20",
      "language": "en",
      "filingTypes": [
        {
          "id": 1,
          "name": "annual",
          "description": "Annual financial reports including Chinese 年度报告"
        }
      ],
      "url": "https://api.filingreader.com/v1/filings/BULL12345/download"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 50,
    "totalItems": 998
  }
}

GET/v1/filings/company/:stockCode/filing-type/:typeName

Get filings for a specific company filtered by filing type name

Parameters:

stockCode(string)required

Stock code (e.g., HKEX:0001)

typeName(string)required

Name of the filing type (e.g., 'annual', 'interim', 'quarterly')

page(integer)

Page number (default: 1)

limit(integer)

Results per page (default: 20, maximum depends on your plan)

startDate(string)

Start date (YYYY-MM-DD)

endDate(string)

End date (YYYY-MM-DD)

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/company/examplestockCode/filing-type/exampletypeName"

Example Response:

{
  "status": "success",
  "data": [
    {
      "bulletinId": "BULL12345",
      "title": "2024 Annual Report",
      "stockCode": "HKEX:0001",
      "timestamp": "2024-03-20T10:30:00Z",
      "createdDate": "2024-03-20",
      "filingTypes": [
        {
          "id": 1,
          "name": "annual",
          "description": "Annual financial reports including Chinese 年度报告"
        }
      ],
      "fileInfo": {
        "fileSize": 2457891,
        "pageCount": 35,
        "hasText": true,
        "isScanned": false,
        "isBroken": false
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 3,
    "totalItems": 5
  }
}

GET/v1/filings/exchange/:exchangeCode/filing-type/:typeName

Filter filings by exchange and filing type

Parameters:

exchangeCode(string)required

Exchange code (e.g., HKEX, SSE, SZSE, BSE, NSE, SET, JSE, TSE, NZX, IDX, LSE, OSL)

typeName(string)required

Name of the filing type (e.g., 'annual', 'interim', 'quarterly')

page(integer)

Page number (default: 1)

limit(integer)

Results per page (default: 20, maximum depends on your plan)

startDate(string)

Start date (YYYY-MM-DD)

endDate(string)

End date (YYYY-MM-DD)

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/exchange/exampleexchangeCode/filing-type/exampletypeName"

Example Response:

{
  "status": "success",
  "data": [
    {
      "title": "2024 Annual Report",
      "company": "Bank of China",
      "stockCode": "HKEX:0001",
      "exchange": "HKEX",
      "filingDate": "2024-03-20",
      "language": "en",
      "filingTypes": [
        {
          "id": 1,
          "name": "annual",
          "description": "Annual financial reports including Chinese 年度报告"
        }
      ],
      "url": "https://api.filingreader.com/v1/filings/BULL12345/download"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 15,
    "totalItems": 142
  }
}

News Endpoints

GET/v1/news

List news stories with filters and pagination

Parameters:

category(string)

Filter by news category (e.g., earnings, mergers, regulation)

startDate(string)

Start date (YYYY-MM-DD)

endDate(string)

End date (YYYY-MM-DD)

page(integer)

Page number

limit(integer)

Results per page

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/news"

Example Response:

{
  "status": "success",
  "data": [
    {
      "id": "n5678",
      "title": "Bank of China Reports Strong Q2 Growth",
      "storyDate": "2024-03-22",
      "category": "earnings",
      "companies": [
        {
          "name": "Bank of China",
          "stockCode": "HKEX:0001"
        }
      ],
      "teaser": "Bank of China reported Q2 earnings above analyst expectations with revenue up 12% YoY...",
      "url": "https://api.filingreader.com/v1/news/id/n5678"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 35,
    "totalItems": 683
  }
}

GET/v1/news/id/:id

Get a specific news story by ID

Parameters:

id(string)required

News ID

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/news/id/exampleid"

Example Response:

{
  "status": "success",
  "data": {
    "id": "n5678",
    "title": "Bank of China Reports Strong Q2 Growth",
    "storyDate": "2024-03-22",
    "category": "earnings",
    "companies": [
      {
        "name": "Bank of China",
        "stockCode": "HKEX:0001"
      }
    ],
    "teaser": "Bank of China reported Q2 earnings above analyst expectations with revenue up 12% YoY...",
    "content": "Bank of China today announced its second-quarter earnings...",
    "source": "FilingReader News Service",
    "sourceUrl": "https://news.filingreader.com/123456"
  }
}

GET/v1/news/company/:stockCode

Get news for a specific company

Parameters:

stockCode(string)required

Stock code including exchange prefix (e.g., HKEX:0001)

limit(integer)

Results per page

Request Examples:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/news/company/examplestockCode"

Example Response:

{
  "status": "success",
  "data": [
    {
      "id": "n5678",
      "title": "Bank of China Reports Strong Q2 Growth",
      "storyDate": "2024-03-22",
      "category": "earnings",
      "companies": [
        {
          "id": "c789",
          "name": "Bank of China",
          "stockCode": "HKEX:0001"
        }
      ],
      "teaser": "Bank of China reported Q2 earnings above analyst expectations with revenue up 12% YoY..."
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 3,
    "totalItems": 26
  }
}

Common Parameters

Pagination

Most list endpoints support pagination:

page: Page number (default: 1)
limit: Results per page (default: 20, maximum depends on your plan)

Example:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/companies?page=2&limit=10"

Date Filtering

Many endpoints support date filtering:

startDate: Start date (YYYY-MM-DD)
endDate: End date (YYYY-MM-DD)

Result Sorting

Filings are automatically sorted by timestamp in descending order (newest first). There is currently no option to change this sorting behavior.

Example:

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings?startDate=2023-01-01&endDate=2023-12-31"

Response Format

All API responses come in a consistent JSON format:

{
  "status": "success",
  "data": {
    "/* The data you requested */": null
  },
  "pagination": {
    "/* Pagination details (for list endpoints) */": null
  }
}

Error responses look like:

{
  "status": "error",
  "message": "Error details here"
}

Code Examples

Get Recent Filings for a Company

# Get filings for a specific company
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/company/HKEX:0001"

# Get filings for a specific company within a date range
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/company/HKEX:0001?startDate=2023-01-01&endDate=2023-12-31"

# Get filings from the last quarter (assuming current date is in 2023-Q3)
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/company/HKEX:0001?startDate=2023-04-01&endDate=2023-06-30"

# Get details for a specific filing
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/BULL12345"

# Download a specific filing
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/BULL12345/download"

# Get all filing types
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filing-types"

# Get filings filtered by type name (annual reports)
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/filing-type/annual"

# Get company filings by type name with date filtering
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/company/HKEX:0001/filing-type/interim?startDate=2022-01-01"

# Get filings from a specific exchange (Hong Kong)
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/exchange/HKEX"

# Get annual reports from a specific exchange (Shanghai)
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/filings/exchange/SSE/filing-type/annual"

# Get companies from a specific exchange (Hong Kong)
curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/companies/exchange/HKEX"

Search Companies by Sector

curl -H "X-API-KEY: your_api_key" "https://api.filingreader.com/v1/companies?sector=Technology&limit=5"

Troubleshooting

Common Issues

Error	Possible Cause	Solution
401 Unauthorized	Invalid API key	Check your API key is correct and active
403 Forbidden	Plan limitations	Your plan doesn't allow this operation
429 Too Many Requests	Rate limit exceeded	Slow down your requests or upgrade plan

Rate Limit Headers

Each response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 986
X-RateLimit-Reset: 1616799429

If you're approaching your limit, slow down your requests or consider upgrading your plan.

Getting Help

If you need assistance with the API:

Email: support@filingreader.com
Status Page: https://status.filingreader.com

Upgrading Your Plan

If you need higher limits or more features:

Email: info@filingreader.com

API Documentation

Contents

Introduction

Getting Started

Authentication

API Plans

Core Endpoints

Available Endpoints

Company Endpoints

Filing Endpoints

Filing Type Endpoints

News Endpoints

Company Endpoints

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Filing Endpoints

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Filing Type Endpoints

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

News Endpoints

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Parameters:

Request Examples:

Example Response:

Common Parameters

Pagination

Date Filtering

Result Sorting

Response Format

Code Examples

Get Recent Filings for a Company

Search Companies by Sector

Troubleshooting

Common Issues

Rate Limit Headers

Getting Help

Upgrading Your Plan