Skip to main content
The Onboarding Profile endpoint is designed specifically for customer onboarding and KYB (Know Your Business) workflows. It provides fast, reliable access to essential company profile information at a fixed, affordable price.

​
Key Features

Fixed Pricing

€0.50 per request regardless of country

Very Fast

P90 response time under 5 seconds

Robust

Uses cached data with automatic fallback to live sources

Targeted

Only supports companyProfile data point - perfect for onboarding

​
When to Use

The Onboarding Profile endpoint is ideal for:
  • Customer Onboarding: Quick company verification during signup flows
  • KYB Processes: Basic company information for Know Your Business checks
  • Lead Qualification: Fast company validation in sales processes
  • Integration Testing: Simplified endpoint for testing integrations
To understand why register data is complex and why this endpoint is necessary, read our guide on Register Data Complexity.
This endpoint is optimized for speed and cost, not for real-time register queries. Data may come from cached sources and is not guaranteed to be from the current day.

​
How It Works

​
Cached Data with Fallback

The endpoint uses a smart caching strategy:
  1. Cache First: Checks for recently cached company data
  2. Automatic Fallback: If no cache exists or cache is too old, fetches fresh data from the register
  3. Background Updates: Keeps cache fresh for future requests
This approach provides the best balance of speed, reliability, and cost.

​
Supported Countries

Currently available for:
  • 🇧🇪 Belgium (BE)
  • 🇩🇰 Denmark (DK)
  • 🇩🇪 Germany (DE)
  • 🇫🇷 France (FR)
  • 🇳🇱 Netherlands (NL)
  • 🇸🇪 Sweden (SE)
  • 🇬🇧 United Kingdom (GB)
For country-specific details about caching behavior, data sources, and fallback logic, see the country-specific documentation pages.

​
Data Normalization

The Onboarding Profile endpoint includes activity normalization to provide standardized industry classification codes:

ISIC Codes

International Standard Industrial Classification (Rev.4) — the global standard for economic activity classification

NACE Codes

Statistical Classification of Economic Activities (Rev.2.1) — the European standard derived from ISIC
This means you get standardized industry codes (marked with isAIInferred: true) alongside the local activity codes, enabling cross-border company comparison by industry.
To optimize for speed and cost, the onboarding endpoint does not include full normalization for: - Legal form ISO 20275 codes - Role ISO 5009 codes - Status standardization (only localName and active boolean) Use the verification data endpoint if you need complete standardization.

​
Differences from /v2/company

Feature/v2/onboarding/v2/company
Data PointsOnly companyProfileAll data points
DocumentsNot supportedSupported
PricingFixed €0.50Variable based on data points
SpeedP90 < 5 secondsVariable
Data SourceCached with fallbackDirect register access
FreshnessMay not be current dayReal-time when available
Activity Codes✅ ISIC & NACE included✅ ISIC & NACE included
Legal Form ISO❌ Not included✅ ISO 20275 codes
Role ISO❌ Not included✅ ISO 5009 codes
Status DetailsBasic (localName + active)Full standardization
Use CaseQuick onboarding/KYBComprehensive data retrieval

​
Example Request

curl --request POST \
  --url https://api.topograph.co/v2/onboarding \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "countryCode": "DE",
    "id": "HRB123456"
  }'

​
Optional: Specify Data Point

While the endpoint defaults to companyProfile, you can explicitly specify it: 
{
  "countryCode": "DE",
  "id": "HRB123456",
  "dataPoints": ["companyProfile"]
}
If you specify dataPoints, it must only contain companyProfile. Any other data points will result in a 400 error.

​
Response Format

The response follows the same structure as /v2/company: 
{
  "request": {
    "requestId": "uuid-v4",
    "companyId": "HRB123456",
    "country": "DE",
    "dataStatus": {
      "dataPoints": {
        "companyProfile": {
          "status": "succeeded",
          "cost": 50
        }
      }
    }
  },
  "company": {
    "id": "HRB123456",
    "countryCode": "DE",
    "legalName": "Example GmbH",
    "status": {
      "localName": "active",
      "active": true
    },
    "legalForm": {
      "localName": "Gesellschaft mit beschränkter Haftung"
    },
    "legalAddress": {
      "addressLine1": "Example Street 1",
      "postalCode": "10115",
      "city": "Berlin",
      "countryCode": "DE"
    },
    "activities": {
      "WZ2008": [
        {
          "code": "62.01",
          "description": "Programmierungstätigkeiten",
          "isAIInferred": false
        }
      ],
      "ISIC": [
        {
          "code": "6201",
          "description": "Computer programming activities",
          "isAIInferred": true
        }
      ],
      "NACE": [
        {
          "code": "62.01",
          "description": "Computer programming activities",
          "isAIInferred": true
        }
      ]
    },
    "registrationDate": "2020-01-01"
  },
  "legalRepresentatives": [
    {
      "type": "individual",
      "role": {
        "localName": "Geschäftsführer"
      },
      "individual": {
        "name": {
          "fullName": "John Doe"
        }
      }
    }
  ]
}
Notice that activities includes both the local classification (WZ2008 for Germany) with isAIInferred: false, and the standardized ISIC and NACE codes with isAIInferred: true. This enables cross-border industry comparison while preserving the original source data.

​
Caching Results

Like the /v2/company endpoint, you can retrieve previously fetched data using the requestId: 
{
  "requestId": "uuid-from-previous-request"
}
This returns cached data without additional charges and is instant.

​
Error Handling

​
400 Bad Request

  • Company ID is missing
  • Invalid data points (only companyProfile allowed)
  • Documents requested (not supported)
{
  "statusCode": 400,
  "error": "Onboarding endpoint only supports companyProfile data point"
}

​
404 Not Found

  • Request ID doesn’t exist or doesn’t belong to your account
{
  "statusCode": 404,
  "error": "Company request does not exist"
}

​
406 Not Acceptable

  • Country not supported yet
{
  "statusCode": 406,
  "error": "Country not supported for onboarding"
}

​
Best Practices

Always store the requestId from initial requests. You can use it to retrieve the same data later at no additional cost.
Even though this endpoint is fast (P90 < 5 seconds), treat responses as potentially asynchronous. Check dataStatus to confirm data availability.
Configure webhooks to receive automatic updates when data becomes available, rather than polling.
This endpoint doesn’t support documents. Use /v2/company if you need official documents.

​
Pricing Details

All requests are billed at €0.50 per request using the ONBOARDING_PROFILE SKU.
  • No variable pricing based on country
  • No additional charges for legal representatives or shareholders included in companyProfile
  • Re-fetching with requestId is free
For comprehensive information about our credit-based billing system and caching behavior, see our Pricing & Caching documentation.

​
Need More Data?

If you need:
  • Ultimate Beneficial Owners (UBOs)
  • Official documents
  • Real-time register data
  • Other data points
Use the verification data endpoint instead.

​
API Reference

For detailed API specifications, request/response schemas, and interactive testing, see:

POST /v2/onboarding

Complete API reference with interactive examples