> ## Documentation Index > Fetch the complete documentation index at: https://docs.topograph.co/llms.txt > Use this file to discover all available pages before exploring further. # Workspaces > Split API usage across sub-accounts, departments, or clients for easy cost tracking and rebilling ## 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. Track exactly how many credits each of your clients consumes Associate each workspace with a legal name for invoicing Pull usage reports programmatically to automate rebilling Store each client's own register logins on their workspace *** ## How It Works ```mermaid theme={null} flowchart LR A[Your Platform] -->|x-topograph-workspace-id: client-a| B[Topograph API] A -->|x-topograph-workspace-id: client-b| B A -->|no header = default| B B --> C[Usage tracked per workspace] C --> D[GET /v2/workspaces/usage] D --> E[Rebill each client] ``` Use `POST /v2/workspaces` to create a workspace with a name and legal entity name. Pass the workspace `name` on every API call: `x-topograph-workspace-id: acme-paris`. If omitted, requests go to the default workspace. Call `GET /v2/workspaces/usage` to get a per-workspace breakdown of credits consumed, filterable by date range. 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 ```bash theme={null} 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" }' ``` ```json Response theme={null} { "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:` can be used verbatim; other characters (spaces, `/`, `@`, `.`) are rejected. ### List Workspaces ```bash theme={null} 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](#ubo-data-access) setting, associated with a workspace: ```bash theme={null} 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 ```bash theme={null} curl -X DELETE "https://api.topograph.co/v2/workspaces/acme-paris" \ -H "x-api-key: YOUR_API_KEY" ``` You cannot delete the **default** workspace, any workspace that has existing requests associated with it, or any workspace that holds saved company batches. *** ## 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. ```bash theme={null} 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`: ```bash theme={null} 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: ```jsonc theme={null} { "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](/guides/webhooks) notification for a completed request, the workspace is included in the payload: ```jsonc theme={null} { "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 ```bash theme={null} curl "https://api.topograph.co/v2/workspaces/usage" \ -H "x-api-key: YOUR_API_KEY" ``` ```json Response theme={null} [ { "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 ```bash theme={null} curl "https://api.topograph.co/v2/workspaces/usage?startDate=2026-03-01&endDate=2026-04-01" \ -H "x-api-key: YOUR_API_KEY" ``` A date is read as midnight UTC at the start of that day, so `endDate` stops where the day you pass begins. To cover all of March, pass `endDate=2026-04-01`. ### Filter by Workspace ```bash theme={null} curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris" \ -H "x-api-key: YOUR_API_KEY" ``` ### Combine Filters ```bash theme={null} curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris&startDate=2026-03-01&endDate=2026-04-01" \ -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**. ```bash theme={null} 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 a workspace's login is cached against your account alone and is never served to another customer. The cache is shared across your own workspaces, so a company fetched under one workspace's login can be reused for another of your workspaces for up to 24 hours. Supported registers, payload shapes, rotation, and what happens when no credential is configured *** ## Use Cases 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 ``` 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 ``` 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. ```python theme={null} # 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"]} ) ``` Set up a cron job to pull usage at the end of each month and generate invoices automatically. ```python theme={null} import requests from datetime import datetime, timedelta, timezone now = datetime.now(timezone.utc) # First day of current month start = now.replace(day=1).strftime("%Y-%m-%d") # endDate stops at midnight UTC, so pass tomorrow to include today end = (now + timedelta(days=1)).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`](/api-reference/workspaces/list-all-workspaces) | GET | List all workspaces | | [`/v2/workspaces`](/api-reference/workspaces/create-a-new-workspace) | POST | Create a workspace | | [`/v2/workspaces/{name}`](/api-reference/workspaces/update-a-workspace) | PATCH | Update a workspace | | [`/v2/workspaces/{name}`](/api-reference/workspaces/delete-a-workspace) | DELETE | Delete a workspace | | [`/v2/workspaces/usage`](/api-reference/workspaces/get-usage-report-per-workspace) | GET | Get usage report | | [`/v2/workspaces/{name}/vault`](/api-reference/vault/list-vault-entries-on-the-workspace-metadata-only) | GET | List the workspace's [register credentials](/essentials/register-credentials) | | [`/v2/workspaces/{name}/vault/{sourceKey}`](/api-reference/vault/create-or-replace-a-credential) | PUT | Store or rotate a register credential | The `x-topograph-workspace-id` header is supported on [/v2/company](/api-reference/data/get-company-data-and-documents) (all modes, including `mode: "prefill"`). The legacy `/v2/onboarding` route also accepts it. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.