Workspaces

Overview

Workspaces let you tag every API request with a sub-account identifier, so you can track and rebill usage per client, department, or entity. This is especially useful for resellers, multi-entity organizations, and platforms that need granular cost attribution. Each workspace has a legal name tied to it, perfect for invoicing and compliance. A workspace also holds its own register credentials, so each client can be checked under their own register account.

Per-Client Billing

Track exactly how many credits each of your clients consumes

Legal Entity Mapping

Associate each workspace with a legal name for invoicing

Usage Reporting API

Pull usage reports programmatically to automate rebilling

Register Credentials

Store each client’s own register logins on their workspace

How It Works

Create workspaces for each client

Use POST /v2/workspaces to create a workspace with a name and legal entity name.

Tag requests with the x-topograph-workspace-id header

Pass the workspace name on every API call: x-topograph-workspace-id: acme-paris. If omitted, requests go to the default workspace.

Pull usage reports

Call GET /v2/workspaces/usage to get a per-workspace breakdown of credits consumed, filterable by date range.

Rebill your clients

Use the usage report to generate invoices for each client based on their actual consumption.

Managing Workspaces

Every account starts with a default workspace. You can create additional workspaces, one per client, department, or legal entity.

Create a Workspace

curl -X POST "https://api.topograph.co/v2/workspaces" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-paris",
    "legalName": "Acme Paris SAS"
  }'

Response

{
  "id": "253299d1-e8d0-4268-945b-f175f98bc114",
  "name": "acme-paris",
  "legalName": "Acme Paris SAS",
  "isDefault": false,
  "uboEnabled": true,
  "createdAt": "2026-03-09T14:00:00.000Z",
  "updatedAt": "2026-03-09T14:00:00.000Z"
}

name is the identifier you use everywhere else. It goes in the x-topograph-workspace-id header and in /v2/workspaces/{name} paths. The UUID id in the response is returned for your own reference only; no endpoint takes it.Names must be alphanumeric with hyphens, underscores and colons only (^[a-zA-Z0-9_:-]+$), max 64 characters, and default is reserved. Colons are allowed so a namespaced tenant key like tenant:<uuid> can be used verbatim; other characters (spaces, /, @, .) are rejected.

List Workspaces

curl "https://api.topograph.co/v2/workspaces" \
  -H "x-api-key: YOUR_API_KEY"

Update a Workspace

Update the legal name, or the UBO data access setting, associated with a workspace:

curl -X PATCH "https://api.topograph.co/v2/workspaces/acme-paris" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legalName": "Acme Paris SAS (updated)"}'

Delete a Workspace

curl -X DELETE "https://api.topograph.co/v2/workspaces/acme-paris" \
  -H "x-api-key: YOUR_API_KEY"

You cannot delete the default workspace, or any workspace that has existing requests associated with it.

UBO Data Access

Every workspace can request ultimate beneficial owner (UBO) data. This is on by default, and controlled through the uboEnabled field on the workspace.

curl -X PATCH "https://api.topograph.co/v2/workspaces/acme-paris" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uboEnabled": false}'

You can set uboEnabled on creation too, or turn it off for an existing workspace at any time. Requesting ultimateBeneficialOwners from a workspace with access turned off returns datapoint_not_supported.

Only keep UBO data access enabled for a workspace whose legal entity is AML-obliged. UBO data carries regulatory obligations under AML law, and Topograph may revoke a workspace’s UBO access if the entity attached to it is not AML-obliged.

Tagging Requests

Add the x-topograph-workspace-id header to any data retrieval or onboarding request. Despite the header’s name, its value is the workspace name, not the UUID id:

curl -X POST "https://api.topograph.co/v2/company" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-topograph-workspace-id: acme-paris" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "443061841",
    "countryCode": "FR",
    "dataPoints": ["company", "legalRepresentatives"]
  }'

The header takes the workspace name, not the UUID id. If it is omitted, the request is automatically tagged to the default workspace. If the name doesn’t exist, the API returns a 404 Not Found; if it contains characters outside [a-zA-Z0-9_:-], a 400 Bad Request.

The workspace tag is propagated to all billing events generated by the request, so every credit consumed is attributed to the correct workspace.

Workspace in API Responses

The workspace is returned in every API response inside the request object:

{
  "request": {
    "requestId": "abc-123",
    "companyId": "443061841",
    "countryCode": "FR",
    "workspace": {
      "name": "acme-paris",
      "legalName": "Acme Paris SAS"
    },
    "dataStatus": { ... }
  },
  "company": { ... }
}

Workspace in Webhooks

When you receive a webhook notification for a completed request, the workspace is included in the payload:

{
  "request": {
    "requestId": "abc-123",
    "companyId": "443061841",
    "countryCode": "FR"
  },
  "workspace": {
    "name": "acme-paris",
    "legalName": "Acme Paris SAS"
  },
  "company": { ... }
}

You can use the workspace info in webhook payloads to automatically route results to the correct client or trigger per-client processing pipelines.

Usage Reporting

The usage report endpoint gives you a per-workspace breakdown of all credits consumed, exactly what you need to rebill your clients.

Get Full Report

curl "https://api.topograph.co/v2/workspaces/usage" \
  -H "x-api-key: YOUR_API_KEY"

Response

[
  {
    "workspace": {
      "name": "default",
      "legalName": "Your Company Inc.",
      "isDefault": true
    },
    "totalCreditsUsed": 42.5,
    "totalRequests": 85,
    "breakdown": [
      { "sku": "example-company-data", "count": 50, "totalCredits": 25.0 },
      { "sku": "example-document", "count": 35, "totalCredits": 17.5 }
    ]
  },
  {
    "workspace": {
      "name": "acme-paris",
      "legalName": "Acme Paris SAS",
      "isDefault": false
    },
    "totalCreditsUsed": 15.0,
    "totalRequests": 30,
    "breakdown": [
      { "sku": "example-company-data", "count": 30, "totalCredits": 15.0 }
    ]
  }
]

Filter by Date Range

curl "https://api.topograph.co/v2/workspaces/usage?startDate=2026-03-01&endDate=2026-03-31" \
  -H "x-api-key: YOUR_API_KEY"

Filter by Workspace

curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris" \
  -H "x-api-key: YOUR_API_KEY"

Combine Filters

curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris&startDate=2026-03-01&endDate=2026-03-31" \
  -H "x-api-key: YOUR_API_KEY"

Register Credentials

A few registers only serve their data to the entity performing the check, or return more of it to accounts holding elevated roles. Germany’s Transparenzregister and France’s INPI both work this way. For those, you store your own register login in Topograph, and you store it on a workspace.

curl -X PUT "https://api.topograph.co/v2/workspaces/acme-paris/vault/de_transparenzregister" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "email": "compliance@acme.example",
      "password": "YOUR_REGISTER_PASSWORD"
    }
  }'

A request tagged x-topograph-workspace-id: acme-paris then runs under that login. If the workspace has no credential of its own, it falls back to the one on the default workspace, so you can either give every client their own register account or share a single house account across all of them. Credentials are encrypted on write and no endpoint ever returns them back. Data fetched under one workspace’s login is cached against that account alone and is never served to anyone else.

Register Credentials

Supported registers, payload shapes, rotation, and what happens when no credential is configured

Use Cases

Resellers / Channel Partners

You resell Topograph to your own clients. Create one workspace per client, tag all their requests, and pull monthly usage reports to generate invoices.

Workspace: client-alpha    -> 120 credits -> client invoice
Workspace: client-beta     -> 45 credits  -> client invoice
Workspace: client-gamma    -> 200 credits -> client invoice

Multi-Entity Organizations

Your company has multiple legal entities or branches. Each entity gets its own workspace with the correct legal name, so you can allocate costs internally.

Workspace: default         -> HQ (Paris)    -> 500 credits
Workspace: london-office   -> London Ltd    -> 200 credits
Workspace: berlin-office   -> Berlin GmbH   -> 150 credits

Platform / SaaS Integration

You build a platform where your users trigger Topograph requests. Tag each request with the user’s workspace to track per-tenant consumption and enforce usage limits.

# In your platform backend
response = requests.post(
    "https://api.topograph.co/v2/company",
    headers={
        "x-api-key": API_KEY,
        "x-topograph-workspace-id": tenant.workspace_name,
    },
    json={"id": company_id, "countryCode": "FR", "dataPoints": ["company", "legalRepresentatives"]}
)

Automated Monthly Rebilling

Set up a cron job to pull usage at the end of each month and generate invoices automatically.

import requests
from datetime import datetime

# First day of current month
start = datetime.now().replace(day=1).strftime("%Y-%m-%d")
end = datetime.now().strftime("%Y-%m-%d")

usage = requests.get(
    f"https://api.topograph.co/v2/workspaces/usage?startDate={start}&endDate={end}",
    headers={"x-api-key": API_KEY}
).json()

for report in usage:
    ws = report["workspace"]
    credits = report["totalCreditsUsed"]
    print(f"Invoice {ws['legalName']}: {credits} credits")

API Reference

Endpoint	Method	Description
`/v2/workspaces`	GET	List all workspaces
`/v2/workspaces`	POST	Create a workspace
`/v2/workspaces/{name}`	PATCH	Update a workspace
`/v2/workspaces/{name}`	DELETE	Delete a workspace
`/v2/workspaces/usage`	GET	Get usage report
`/v2/workspaces/{name}/vault`	GET	List the workspace’s register credentials
`/v2/workspaces/{name}/vault/{sourceKey}`	PUT	Store or rotate a register credential

The x-topograph-workspace-id header is supported on /v2/company (all modes, including mode: "onboarding"). The legacy /v2/onboarding route also accepts it.

Getting Started

Integration Guides

Core Features

Behavior & Operations

Overview

Per-Client Billing

Legal Entity Mapping

Usage Reporting API

Register Credentials

How It Works

Managing Workspaces

Create a Workspace

List Workspaces

Update a Workspace

Delete a Workspace

UBO Data Access

Tagging Requests

Workspace in API Responses

Workspace in Webhooks

Usage Reporting

Get Full Report

Filter by Date Range

Filter by Workspace

Combine Filters

Register Credentials

Register Credentials

Use Cases

API Reference

​Overview

Per-Client Billing

Legal Entity Mapping

Usage Reporting API

Register Credentials

​How It Works

​Managing Workspaces

​Create a Workspace

​List Workspaces

​Update a Workspace

​Delete a Workspace

​UBO Data Access

​Tagging Requests

​Workspace in API Responses

​Workspace in Webhooks

​Usage Reporting

​Get Full Report

​Filter by Date Range

​Filter by Workspace

​Combine Filters

​Register Credentials

Register Credentials

​Use Cases

​API Reference

Overview

How It Works

Managing Workspaces

Create a Workspace

List Workspaces

Update a Workspace

Delete a Workspace

UBO Data Access

Tagging Requests

Workspace in API Responses

Workspace in Webhooks

Usage Reporting

Get Full Report

Filter by Date Range

Filter by Workspace

Combine Filters

Register Credentials

Use Cases

API Reference