> ## 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. # Find a company across countries from its name > Takes what you know about a company in one free-text `query` (the name plus a city, a country, a registration number, a website…), or a `name` with structured `hints`, and returns ranked candidates across the countries Topograph covers, each with a registration number you can pass to `/v2/company`, a confidence and an explanation of the evidence. The search is agentic and bounded: it reads the legal form and any address, checks Topograph's index, asks the web when the name and that data are not enough, confirms in the most likely registers (US states included), and stops as soon as one candidate is a strong match. At most 15 live and web searches, at most 100 seconds. **Status.** `resolved`: one strong match. `ambiguous`: several plausible candidates (the same name in two countries, a US company whose state is not established), all returned with their evidence. `not_found`: nothing acceptable; `reason` says why, and `query.discoveredCountryCode` names the country the evidence pointed to even when Topograph does not cover it. **Alpha.** The request and response shapes may still change. **Billing.** A search is billed only when it succeeds: `status: resolved`, one good candidate. Ambiguous and not-found searches, inputs rejected as not a legal entity, failures and timeouts are not billed. `usage.priceCents` shows what was charged; the price is on the pricing page. **Streaming.** With `stream: true` and `Accept: text/event-stream`, the endpoint emits `progress` events (the plan so far: steps, country assessments, candidates), then one `complete` event with the final response, or an `error` event. ## OpenAPI ````yaml post /v2/search/global openapi: 3.0.0 info: title: Topograph description: The Topograph API version: '0.1' contact: {} servers: - url: https://api.topograph.co security: - x-api-key: [] tags: [] paths: /v2/search/global: post: tags: - Search summary: Find a company across countries from its name description: >- Takes what you know about a company in one free-text `query` (the name plus a city, a country, a registration number, a website…), or a `name` with structured `hints`, and returns ranked candidates across the countries Topograph covers, each with a registration number you can pass to `/v2/company`, a confidence and an explanation of the evidence. The search is agentic and bounded: it reads the legal form and any address, checks Topograph's index, asks the web when the name and that data are not enough, confirms in the most likely registers (US states included), and stops as soon as one candidate is a strong match. At most 15 live and web searches, at most 100 seconds. **Status.** `resolved`: one strong match. `ambiguous`: several plausible candidates (the same name in two countries, a US company whose state is not established), all returned with their evidence. `not_found`: nothing acceptable; `reason` says why, and `query.discoveredCountryCode` names the country the evidence pointed to even when Topograph does not cover it. **Alpha.** The request and response shapes may still change. **Billing.** A search is billed only when it succeeds: `status: resolved`, one good candidate. Ambiguous and not-found searches, inputs rejected as not a legal entity, failures and timeouts are not billed. `usage.priceCents` shows what was charged; the price is on the pricing page. **Streaming.** With `stream: true` and `Accept: text/event-stream`, the endpoint emits `progress` events (the plan so far: steps, country assessments, candidates), then one `complete` event with the final response, or an `error` event. operationId: GlobalSearchController_globalSearch_v2 parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GlobalSearchRequestDto' responses: '200': description: >- The ranked candidates and the explained plan (JSON), or the SSE stream when `stream` is true. content: application/json: schema: $ref: '#/components/schemas/GlobalSearchResponse' text/event-stream: schema: type: string description: >- Named events: `progress` (GlobalSearchProgress), `complete` (GlobalSearchResponse), `error`. example: >- event: progress data: {"isComplete":false,"candidates":[],"countries":[...],"steps":[...]} event: complete data: {"status":"resolved",...} '400': description: Invalid request (empty name, unknown country code in the hints). content: application/json: schema: type: object properties: statusCode: type: number example: 400 error: type: object properties: code: type: string example: invalid_request message: type: string example: name is required and cannot be empty '402': description: Not enough credits for a run. content: application/json: schema: type: object properties: statusCode: type: number example: 402 error: type: object properties: code: type: string example: insufficient_funds message: type: string example: Not enough credits for a global search. '429': description: >- Fair-use limit: too many runs this minute, or too many running at once, for this account. content: application/json: schema: type: object properties: statusCode: type: number example: 429 error: type: object properties: code: type: string example: rate_limited message: type: string example: >- Too many global searches this minute for this account. Retry shortly. '503': description: The run exceeded its time limit. content: application/json: schema: type: object properties: statusCode: type: number example: 503 error: type: object properties: code: type: string example: search_timeout message: type: string example: The global search took too long to complete. security: - x-api-key: [] components: schemas: GlobalSearchRequestDto: type: object properties: query: type: string description: >- Free text: the company name plus anything you know, in one string ("Bamberger GmbH, Wien", "MFG Investments EOOD, from a UK filing", "Altria Group Inc., Richmond VA, altria.com"). The name and the hints are extracted for you. Give either `query` or `name`. example: Bamberger GmbH, Wien name: type: string description: >- The company name alone, when you prefer to pass structured `hints` yourself. Legal-form suffixes, OCR noise and parenthesised aliases are handled. example: Bamberger GmbH hints: $ref: '#/components/schemas/GlobalSearchHints' activeOnly: type: boolean description: Only companies the registers report as active. example: false stream: type: boolean description: >- Streaming mode: Server-Sent Events with `progress` events (the steps so far, and the candidates found so far), one `complete` event carrying the final response, or an `error` event. Set Accept to `text/event-stream`. example: false GlobalSearchResponse: type: object properties: status: description: >- `resolved`: one strong match. `ambiguous`: several plausible candidates, or one weak one. `not_found`: nothing acceptable; see `reason`. allOf: - $ref: '#/components/schemas/GlobalSearchStatus' reason: description: Why the search ended `not_found`, or why it stopped early. allOf: - $ref: '#/components/schemas/GlobalSearchReason' summary: type: string description: The outcome in one sentence. example: 'Found in Austria: Bamberger GmbH (370916s).' query: description: What was understood from your input. allOf: - $ref: '#/components/schemas/GlobalSearchQuery' candidates: description: Ranked candidates. Empty on `not_found`. type: array items: $ref: '#/components/schemas/GlobalSearchCandidate' countries: description: The countries considered, and what happened in each. type: array items: $ref: '#/components/schemas/GlobalSearchCountry' steps: description: The search, step by step. type: array items: $ref: '#/components/schemas/GlobalSearchStep' usage: $ref: '#/components/schemas/GlobalSearchUsage' required: - status - summary - query - candidates - countries - steps - usage GlobalSearchHints: type: object properties: countries: description: >- Countries you believe in, most likely first. Topograph country codes; US states as `US-DE`. example: - DE - AT type: array items: type: string excludeCountries: description: Countries already searched without a hit; never searched again. example: - GB type: array items: type: string sourceCountry: type: string description: >- The register that emitted the name, when the name comes from a filing (a foreign holder's stated domicile). A weak signal. example: IT address: description: >- Free-text address, or a structured one (see GlobalSearchAddressHint). Parsed with a dictionary, then geocoded when needed. oneOf: - type: string - d30b9308-e436-43dd-8708-2ca5f6cd4e43 example: Via Roma 1, 20121 Milano, Italia legalForm: type: string description: Legal form as you know it, when the name does not carry it. example: GmbH identifier: type: string description: Any registration, VAT or LEI number, in any format. example: DE812345678 website: type: string description: Company website; a national TLD is a country signal. example: https://example.fr GlobalSearchStatus: type: string enum: - resolved - ambiguous - not_found description: >- `resolved`: one strong match. `ambiguous`: several plausible candidates, or one weak one. `not_found`: nothing acceptable; see `reason`. GlobalSearchReason: type: string enum: - not_a_legal_entity - no_country_signal - country_not_covered - no_register_match - search_limit_reached - timeout description: Why the search ended `not_found`, or why it stopped early. GlobalSearchQuery: type: object properties: text: type: string description: What you sent. example: Bamberger GmbH, Wien name: type: string description: The company name read out of it. example: Bamberger GmbH latinName: type: string description: Latin spelling, when the name is written in another script. legalForm: type: string description: The legal form found in the name. example: GmbH hints: description: 'The hints used: read out of the text, plus any you passed.' allOf: - $ref: '#/components/schemas/GlobalSearchHints' likelyCountryCode: type: string description: >- The country the evidence points to, even when the company could not be confirmed or Topograph does not cover its register. example: KY required: - text - name - hints GlobalSearchCandidate: type: object properties: rank: type: number description: 1 is the best candidate. match: description: >- `strong`: this is the company, as far as the evidence goes. `possible`: a plausible candidate that needs a second look. allOf: - $ref: '#/components/schemas/GlobalSearchMatchStrength' countryCode: type: string description: >- Topograph country code; US states as `US-DE`. Use it with `/v2/company`. example: AT id: type: string description: Registration number in that register, as `/v2/company` expects it. example: 370916s legalName: type: string example: Bamberger GmbH legalNameInEnglish: type: string companyNameTransliterations: type: array items: type: string address: $ref: '#/components/schemas/AddressDTO' isActive: type: boolean description: Whether the register reports the company as active, when known. explanation: $ref: '#/components/schemas/GlobalSearchExplanation' required: - rank - match - countryCode - id - legalName - explanation GlobalSearchCountry: type: object properties: countryCode: type: string example: DE outcome: description: What happened in this country. allOf: - $ref: '#/components/schemas/GlobalSearchCountryOutcome' explanation: type: string description: The outcome as a sentence. example: 'Germany: the register returned no company of that name.' required: - countryCode - outcome - explanation GlobalSearchStep: type: object properties: index: type: number kind: allOf: - $ref: '#/components/schemas/GlobalSearchStepKind' status: description: >- `running` while the step is in progress (streaming only), `done` once it finished. allOf: - $ref: '#/components/schemas/GlobalSearchStepStatus' countryCode: type: string description: The country the step is about, for register steps. label: type: string description: What the step does or did, as a sentence you can show a user. example: Asking the register in Austria required: - index - kind - status - label GlobalSearchUsage: type: object properties: priceCents: type: number description: >- What this search was charged, in credit cents. 0 unless `status` is `resolved`. durationMs: type: number required: - priceCents - durationMs GlobalSearchMatchStrength: type: string enum: - strong - possible description: >- `strong`: this is the company, as far as the evidence goes. `possible`: a plausible candidate that needs a second look. AddressDTO: type: object properties: addressLine1: type: string description: First line of the address example: 10 rue de la Fraternité addressLine2: type: string description: Second line of the address example: Topograph Building city: type: string description: City of the address example: Bagnolet postalCode: type: string description: Postal code of the address example: '93170' region: type: string description: Region of the address example: FR countryCode: type: string description: Country of the address using ISO 3166-1 alpha-2 country code example: FR poBox: type: string description: Post Office Box number example: PO Box 123 careOf: type: string description: Care of (c/o) recipient example: c/o John Doe state: type: string description: State of the address example: Île-de-France latitude: type: number description: Latitude coordinate example: 59.9139 longitude: type: number description: Longitude coordinate example: 10.7522 GlobalSearchExplanation: type: object properties: summary: type: string description: Why this candidate matched, in one or two sentences. reasons: description: The reasons, one per line. type: array items: $ref: '#/components/schemas/GlobalSearchMatchReason' required: - summary - reasons GlobalSearchCountryOutcome: type: string enum: - match - no_match - not_searched - not_covered - excluded - unavailable description: What happened in this country. GlobalSearchStepKind: type: string enum: - reading_name - company_data - address - public_sources - register - rephrasing - deciding - rejected GlobalSearchStepStatus: type: string enum: - running - done description: >- `running` while the step is in progress (streaming only), `done` once it finished. GlobalSearchMatchReason: type: object properties: kind: description: What kind of reason this is. allOf: - $ref: '#/components/schemas/GlobalSearchMatchReasonKind' text: type: string description: The reason as a sentence you can show a user. example: The register in Austria lists it under exactly that name countryCode: type: string description: The country the reason is about. example: AT url: type: string description: '`public_source` only: the page that states it.' example: >- https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000764180 required: - kind - text GlobalSearchMatchReasonKind: type: string enum: - legal_form - address - country_hint - source_filing - website - identifier - company_data - public_source - register_match - address_match - distance description: What kind of reason this is. securitySchemes: x-api-key: type: apiKey in: header name: x-api-key ````