GET /api/v1/search
Find a company three ways, by how much your system already knows. The more structure you pass, the more deterministic the call — no LLM is involved unless you use free text.
Input modes
| YOU KNOW | PASS | BEHAVIOR |
|---|---|---|
| The registration number | registrationNumber + country | Exact lookup — 0 or 1 results, no search, no LLM. interpretation.matchedBy: "registration_number" |
| Name + country | name + country | Deterministic registry search in that country, no LLM. Legal-form suffixes ("S.A.B. de C.V.", "LTDA") are stripped. routedBy: "caller" |
| Only a description | q | Free text — the Search Agent routes it. routedBy: "search_agent" |
Modes are exclusive — mixing q with structured params returns 400 conflicting_parameters. A country whose registry has no number-lookup yet returns 422 unsupported_lookup_for_country.
Structured lookup example
curl -H "x-api-key: vk_live_…" \
"https://app.verety.ai/api/v1/search?country=BR®istrationNumber=07918048"
{
"interpretation": { "country": "BR", "matchedBy": "registration_number" },
"results": [{ "id": "cnpj-07918048", "name": "…",
"taxId": { "label": "CNPJ", "value": "07918048", "confidence": "confirmed" } }],
"registriesQueried": 1
}
Response
| FIELD | DESCRIPTION |
|---|---|
interpretation.country | ISO 3166-1 alpha-2 the query was routed to, or null. |
interpretation.searchText | The company name after stripping filler words. |
interpretation.routedBy | search_agent — the agent routed the query · none — routing unavailable, searched all entitled countries. |
results[].id | Entity id — pass to /v1/entity/{id} or /v1/investigate. |
results[].name | Legal name as recorded by the registry. |
results[].country | ISO country code. |
results[].registry | Which registry answered (e.g. RFB / CNPJ REGISTRY, INEGI DENUE). |
results[].registryRef | The record's key in that registry. |
results[].location | Registered address when the registry provides one, else null. |
results[].taxId | {label, value, confidence}. Confidence: confirmed (the registry's own key) · candidate (resolved, partially corroborated) · pending (resolvable on request). |
registriesQueried | How many registries actually answered — not how many were asked. |
note | Present only when results are empty for a reason: country_not_entitled (the query routed to a country outside your key) or country_not_supported (no registry for that country yet — supportedCountries lists what is covered). We never silently search elsewhere. |
Example
curl -H "x-api-key: vk_live_…" "https://app.verety.ai/api/v1/search?q=petrobras+brazil"
{
"query": "petrobras brazil",
"interpretation": { "country": "BR", "searchText": "petrobras", "routedBy": "search_agent" },
"results": [{
"id": "cnpj-07918048", "name": "ASSOCIACAO DESPORTIVA CLASSISTA PETROBRAS NORTE",
"country": "BR", "registry": "RFB / CNPJ REGISTRY", "registryRef": "07918048",
"location": null,
"taxId": { "label": "CNPJ", "value": "07918048", "confidence": "confirmed" }
}],
"registriesQueried": 1
}