​
Downloading Documents Safely

Topograph delivers document download links as signed URLs with a 15-minute lifespan. Each time you call /v2/company with the requestId from your original request, the API regenerates fresh signed URLs. We recommend either downloading files immediately or reusing /v2/company with the stored requestId when you need a new link. 
POST https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "requestId": "253299d1-e8d0-4268-945b-f175f98bc114"
  }'

​
Automatic PDF Post-Processing

Some registries publish documents in formats such as TIFF, XLS/XLSX, DOC/DOCX, or PPT. When a file requires conversion, the document remains listed in the response with the original url, but the processing status under request.dataStatus.documents stays in_progress until the conversion completes (typically ~20 seconds). In critical workflows, you can use the original url immediately if you do not need the PDF. Once conversion finishes, the document payload includes:
  • url: the original file provided by the registry
  • pdfUrl: a PDF generated by Topograph (when available)
If the source already supplies a PDF, url and pdfUrl are identical. We are working on introducing more granular document statuses in the coming weeks.

​
Best Practices

  • Store request IDs: When you acquire documents, keep the requestId so you can refresh signed URLs later without extra cost.
  • Plan download timing: Because signed URLs expire quickly, build your workflow to download or refresh links promptly.
  • Monitor status: Watch request.dataStatus.documents[docId].status. If it is still in_progress, a background conversion may be running.

​
AI-Powered Financial Data Extraction

Topograph automatically extracts structured financial data from PDF financial statements using advanced AI technology. This feature requires no additional configuration - extraction happens automatically during document post-processing.

​
How It Works

When a financial statement document is retrieved, our system:
  1. Analyzes the PDF content to determine if it’s a financial statement
  2. Extracts key financial metrics and metadata if applicable
  3. Returns the structured data in the extractedData.financialData field

​
Example Response

Here’s an example of a financial statement with extracted data: 
{
  "request": {
    "companyId": "München HRB 228960",
    "requestId": "2f89e7ba-dfc6-45fc-aa0c-a32d98ca37f7",
    "dataStatus": {
      "documents": {
        "publication-f10798ab5f83": {
          "cost": 0,
          "status": "succeeded"
        }
      },
      "dataPoints": {}
    },
    "countryCode": "DE"
  },
  "documents": {
    "financialStatements": [
      {
        "id": "publication-f10798ab5f83",
        "date": "2024-02-15",
        "name": "Jahresabschluss zum Geschäftsjahr vom 01.01.2022 bis zum 31.12.2022",
        "format": "pdf",
        "period": {
          "endDate": { "day": 31, "year": 2022, "month": 12 },
          "startDate": { "day": 1, "year": 2022, "month": 1 }
        },
        "description": "Annual financial statement for 2022",
        "extractedData": {
          "financialData": {
            "currency": "EUR",
            "fiscalYear": {
              "endDate": "2022-12-31",
              "startDate": "2022-01-01"
            },
            "approvalDate": "2024-01-02",
            "accountingStandard": "Other",
            "statementType": "simplified",
            "incomeStatement": {
              "revenue": {
                "amount": 150469.06,
                "localName": "Rohergebnis",
                "previousAmount": 1359378.83
              },
              "netIncome": {
                "amount": -373040.93,
                "localName": "Jahresfehlbetrag",
                "previousAmount": -900540.73
              }
              // ... more fields
            },
            "balanceSheet": {
              "assets": {
                "fixedAssets": {
                  /* ... */
                },
                "currentAssets": {
                  /* ... */
                }
              },
              "equityAndLiabilities": {
                "equity": {
                  /* ... */
                },
                "liabilities": {
                  /* ... */
                }
              }
            }
          }
        },
        "url": "https://..."
      }
    ]
  }
}

​
Key Points

  • Automatic processing - No extra API calls or configuration needed
  • Non-financial documents - Documents that aren’t financial statements will not have the extractedData field
  • Language agnostic - Works with financial statements in various languages
  • Beta feature - The data model may evolve based on user feedback
For detailed information about the financial data model and all available fields, see our Financial Data Extraction documentation. For a broader picture of how document retrieval fits in the company flow, return to the Retrieve Company data guide.