Company information through API v3
API specifications
REST API service with JSON responses for accessing company data, financial indicators and predictive insolvency risk directly from your own applications.
Company information can be accessed directly from your ERP, CRM, or other applications through this service.
The service is a REST API with JSON responses and can be accessed only by users for whom the service has been activated. To activate the API service and generate the key, click the reset button in the account update form. API queries follow the specific rules presented below. Information from detailed reports is not available through the API.
Billable API queries are paid in credits, and the same information can be accessed regardless of the eligible access package type. For info-v3 queries, credit usage depends on the information requested and returned, meaning credits are consumed only for the information actually received from what you asked for. A search-v3 request made exclusively using a valid CUI is free. The credit cost is the same regardless of package type or options, and if multiple valid eligible packages exist, the oldest eligible package is used by default. The available balance includes both whole credits from active packages and a fractional balance, and responses expose both the cost and remaining balance with two decimals through the cost and credits fields.
Searches by name, CUI, or J
Search helps identify the CUI required for point queries.
To query information about a company, you need to know its CUI. If you do not know the CUI, you can use the search endpoint to find the company by name, VAT number, registration number or other identifying data, then use the returned CUI in info-v3 queries.
Search requests are sent using HTTP, preferably POST, to:
https://listafirme.ro/api/search-v3.asp
The query parameters are:
- key = the secret API key that you can find in your account details if the service is activated;
- src = the text to search; it must have at least 3 characters.
The src parameter can be used for three types of searches, depending on the options included in the active API plan: simple search, extended search and advanced search.
If you send the request via GET, the src parameter value must be URL-encoded when it contains spaces, quotes or other special characters. Most HTTP libraries perform this encoding automatically.
Simple search
Simple search does not use special prefixes and is suitable for company name, CUI or registration number. A search made exclusively using a valid CUI is free.
key=<key>&src=Borg Design key=<key>&src=14837428 key=<key>&src=J2002008118400
Extended search
Extended search is intended to identify the company by website, email address, landline or mobile phone. It does not use distinct prefixes; the search type is inferred automatically from the value sent in src.
key=<key>&src=borg.ro key=<key>&[email protected] key=<key>&src=0211234567 key=<key>&src=0722123456
Extended search can be used only if the active API plan includes the Extended search or Advanced search option.
Advanced search
Advanced search allows queries by explicit criteria, using prefixes inside src. The accepted prefixes are:
- ADM: individual administrator
- ASF: individual shareholder
- ASJ: corporate shareholder
- ADR: registered-office address
- COD: postal code
- LOC: city or locality
- JUD: county
- ACT: NACE code / activity
- DES: text searched in the company description
- ANT: former company name
- NOT: text searched in your own notes saved in the account
key=<key>&src=ADM:"Popescu Ion" key=<key>&src=ASF:"Popescu Ion" key=<key>&src=ASJ:"Borg Design SRL" key=<key>&src=ADR:"Str. Unirii" key=<key>&src=COD:400123 key=<key>&src=LOC:"Cluj-Napoca" key=<key>&src=JUD:CJ key=<key>&src=ACT:6201 key=<key>&src=DES:"dezvoltare software" key=<key>&src=ANT:"Nume Vechi SRL" key=<key>&src=NOT:"client prioritar"
You can combine multiple criteria in the same src expression. For multi-word expressions, using double quotes is recommended.
key=<key>&src=ADM:"Popescu Ion" JUD:Cluj key=<key>&src=ASF:"Popescu Ion" ACT:6201 key=<key>&src=DES:"software gestiune" LOC:"Bucuresti"
Advanced search can be used only if the active API plan includes the Advanced search option.
Using the search endpoint requires an active API service, a valid API key and an API-compatible access plan. Available credit balance is required only for billable searches; a search made exclusively using a valid CUI can also be used with a zero balance. The unlimited monthly plan is not eligible for API usage. If the expression sent in src requires a search type not included in the active plan, the request will be rejected.
For the example search made exclusively using CUI 14837428, the response has the following form:
{"Results":[{"Name":"BORG DESIGN SRL","FiscalCode":"14837428","County":"BUCURESTI","URL":"https://platform.listafirme.ro/borg-design-srl-14837428/"}],"hasMore":false,"cost":"0.00","credits":"123.18"}
The schema of each element in Results is:
{
"Name": "string",
"FiscalCode": "string",
"County": "string",
"URL": "string"
}
The search response schema is:
{
"Results": [ ... ],
"hasMore": false,
"cost": "string",
"credits": "string"
}
The response returns at most 50 results per query.
If there are more than 50 eligible results, the response is truncated to the first 50 and the hasMore field is true.
If no results are identified, the response does not include an error and returns Results as an empty list, hasMore=false, plus the query cost and remaining balance.
Search requests are meant to facilitate detailed information queries. A search-v3 request made exclusively using a valid CUI costs 0.00 and does not change the balance. Any other search consumes a fixed 0.02 credits, including a search in which the CUI is combined with other criteria. For billable searches, the cost is charged fractionally using the same decimal balance mechanism as info queries. Free usage does not remove the requirements for an active API service, a valid key and an API-compatible access plan.
Point queries for company information
Point queries use the company CUI and a JSON object with the requested data.
Knowing the company CUI, information queries are sent over HTTP, preferably POST, to:
https://listafirme.ro/api/info-v3.asp
The query parameters are:
- key = the secret API key that you can find in your account details if the service is activated;
- data = JSON object specifying the requested data.
TaxCode is mandatory, and besides it you must list in the JSON object at least one more property that you want to receive.
Query example:
key=<key>&data={"TaxCode":"14837428","Name":"","Status":""}
It would return a JSON response like the one below:
{
"TaxCode": "14837428",
"Status": "functiune",
"Name": "BORG DESIGN SRL",
"cost": "0.03",
"credits": "122.97"
}
Available parameters and costs
List in the JSON object only the properties that you want to receive.
The available point data, which you should list as properties in the JSON object (data) only for the fields you want, are:
In the request, property values are usually empty strings. Except for explicitly documented exceptions, the transmitted values are ignored even if they are null or arbitrary text. The Returned type column describes the response data shape, including any documented cardinality limits, while the Special request values column shows only the exceptions that change this default behavior.
| Select | Parameter | Description | Returned type | Special request values | Credits |
|---|---|---|---|---|---|
| TaxCode | The CUI of the requested company | string | [cui] | 0 | |
| VAT | VAT payer / non-payer | boolean | - | 0.03 | |
| RegNo | Trade Register registration number | string | - | 0.03 | |
| Status | Current operating status of the company | string | - | 0.03 | |
| LegalForm | Legal form | string | - | 0.03 | |
| EntityType | Entity type when the company is a branch, subsidiary, or another similar unit | string | - | 0.13 | |
| Name | Company name | string | - | 0.03 | |
| NACE | NACE code of the main line of business, in the current revision available for the company | string / object | -,info | 0.06 | |
| PrincipalNACE | Main NACE codes of the company, grouped together with the common revision | array<object> max. 1 | - | 0.06 | |
| Date | Company incorporation date | string | - | 0.03 | |
| TownCode | SIRUTA code of the locality | string | - | 0.03 | |
| County | County | string | - | 0.03 | |
| City | City / locality | string | - | 0.03 | |
| Address | Postal address | string | - | 0.28 | |
| Validity | Validity period of the registered office | string | - | 0.28 | |
| Inactive | Current ANAF fiscal inactivity status | boolean | - | 0.03 | |
| ContactPerson | Contact person | object | - | 0.19 | |
| Administrators | List of directors | array<object> | - | 0.38 | |
| Shareholders | List of shareholders / associates | array<object> | - | 0.38 | |
| Beneficiary | List of beneficial owners | array<object> | - | 0.38 | |
| Turnover | Turnover for the latest year and the latest year with a filed financial statement | string | - | 0.06 | |
| Profit | Net profit for the latest year and the latest year with a filed financial statement | string | - | 0.06 | |
| InsolvencyRisk | Predictive insolvency risk as a percentage, the financial statement year used and the prediction period year | object | - | 0.06 | |
| Employees | Average number of employees for the latest year and the latest year with a filed financial statement | string | - | 0.06 | |
| Balance | Financial statement information for all years by default, or for the year specified as parameter | array<object> | [an], latest | 1.13-0.57 | |
| Phone | Landline phone numbers | array<string> max. 2 | - | 0.28 | |
| Mobile | Mobile phone numbers | array<string> max. 2 | - | 0.28 | |
| Email addresses | array<string> max. 2 | - | 0.44 | ||
| Web | Website addresses | array<string> max. 2 | - | 0.44 | |
| Geolocation | Latitude and longitude | object | - | 0.06 | |
| Description | Company description | string (plain text) | - | 0.13 | |
| Trademarks | Registered trademarks | array<string> max. 5 | - | 0.38 | |
| Marketplaces | Marketplaces where the company has an offer or public page | array<object> | - | 0.13 | |
| Subsidiaries | Number of branches | string | - | 0.06 | |
| Branches | Number of secondary offices | string | - | 0.06 | |
| FiscalActivity | ANAF activity status | object | - | 0.19 | |
| Obligations | Current outstanding tax obligations aggregated by budgets | object | - | 0.25 | |
| BPI | Latest known BPI bulletin for the company | object | - | 0.19 | |
| FormerNames | History of previous company names | array<object> | - | 0.32 | |
| WorkLocations | Known work locations of the company | array<object> max. 100 | active | 0.44 | |
| SEAP | Boolean signals for public tenders and direct sales through SEAP | composite logical object | - | 0.13 | |
| Links | Directly connected companies | array<object> | - | 0.38 |
Estimated average cost / query
0.01
Maximum cost / query
0.01
The average cost is lower because missing values and some default values of requested fields are not charged at all, for example outstanding obligations are not charged when they are zero.
TaxCode is included automatically. Select at least one more parameter for a valid query.
Test example with the options above, ready to copy:
Do NOT use GET in production; reset the API key after testing.
Cost rules
Costs are calculated only for the information requested and actually returned.
The total credit cost of each query is the sum of the costs of the requested and returned information. The API charges only for information that exists and is actually returned in the response, and the cost exposed in JSON is a string with two decimals.
The available balance is the sum of whole credits from active plans and a fractional balance. If a query can be fully covered from the fractional part, the whole credits are not affected. If the fractional balance is not enough, the remaining total balance is recalculated, the whole part is deducted from credits, and the fractional part is kept separately for future queries.
The API returns values for any property listed in the JSON if the information is known. Property values in the JSON request are ignored except for TaxCode (which is mandatory), NACE which may have the value "info" to include the code and the descriptions corresponding to the reference set it comes from, Balance where the desired year may be specified (for example 2014) or the word "latest" for the most recent financial statement, and WorkLocations where the value "active" filters only active work locations. The code revision is returned separately in NACERev. Any other value for Balance or WorkLocations is ignored.
The service does not implicitly convert between CAEN Rev.2 and Rev.3. For company-level NACE, the current code from the companies table is returned together with its revision, and in Balance the historical code for that year is returned together with the revision corresponding to that financial statement.
Logical fields are returned as real JSON boolean values, not as strings. Examples: VAT, ContactPerson.Active, Administrators[].Active, Geolocation.Approximated and FiscalActivity.History.
Description is returned as plain text, without HTML markup.
When you request Turnover, Profit or Employees, the response also includes the Year property for the year to which the returned values refer.
InsolvencyRisk returns the predictive insolvency risk shown in the company profile, as an object with three strings: Percentage (a percentage between 0 and 100, with two decimals, a decimal point and no % sign), BalanceYear (the financial statement year used) and PredictionYear (the prediction period year). The value sent for InsolvencyRisk in the request is ignored.
Currently, the prediction based on the 2025 financial statement is used. If it is missing, the prediction based on 2024 is used when available. In both cases, PredictionYear is "2026". For example: {"InsolvencyRisk":{"Percentage":"0.00","BalanceYear":"2025","PredictionYear":"2026"}}. The years in this object do not change the Year property associated with financial indicators.
The entire InsolvencyRisk object has the same price as a single Turnover or Profit field, including all three values. Percentage="0.00" is a valid result and is charged when the object is returned. If no prediction is available or a technical error occurs while retrieving it, the object is omitted completely and is not charged; the other requested properties continue to be processed.
When you request NACE, the response also includes the NACERev property. In Balance objects, the NACE and NACERev fields describe the CAEN code and revision valid for that financial year, while AdvanceIncome and AdvanceExpenses appear only in the years for which those values exist.
The service does not return values for parameters that were not specified in the query or for which no data exists. If a requested parameter is missing from the response, it means there was no information to return.
When you request SEAP, the response may include both the SEAPPublicTenders and SEAPDirectSales keys at the same time. If the company has neither public tenders nor direct sales through SEAP, neither key is returned.
For certain data types (for example FiscalActivity, Obligations, BPI, FormerNames, WorkLocations, Marketplaces or SEAP), information is returned only if the company is listed in the relevant sources or if there is actual data to expose. If these properties were requested but are missing from the response, the correct interpretation is that there was no public information to return, the queried company did not qualify for that data, or, for accepted filters such as WorkLocations="active", no eligible results remained at query time.
The response specifies the query cost in credits and the total number of remaining credits in the credits field.
In the consumption log, only the actual whole-number part deducted from credits is stored. If the charge was covered exclusively from the fractional balance, no whole-credit decrease is recorded.
For testing and cost evaluation based on the requested data, you may query VAT No. 14837428 free of charge. In cases where certain data cannot be returned for specific queries, the cost decreases compared with the estimate above.
JSON Schema
Formal artifact for automated validation in applications, SDKs and AI systems.
In addition to the explanations on this page, a JSON Schema bundle is also available at:
/specificatii/api-v3-schema.asp
The bundle contains three main definitions in $defs :
- #/$defs/errorResponse = shared schema for error responses
- #/$defs/searchSuccess = schema for the successful response of the /api/search-v3.asp endpoint
- #/$defs/infoSuccess = schema for the successful response of the /api/info-v3.asp endpoint
The formal schema includes types, the definition of returned composite objects, optional fields, documented cardinality limits, and format validation for cost and credits.
Integration examples
Quick GET and POST examples, plus a complete reference response.
Simple GET search example, useful only for quick tests:
https://listafirme.ro/api/search-v3.asp?key=yourkey&src=Borg Design
Recommended POST search example:
POST https://listafirme.ro/api/search-v3.asp Content-Type: application/x-www-form-urlencoded key=yourkey&src=Borg Design
Simple GET point query example, useful only for quick tests:
https://listafirme.ro/api/info-v3.asp?key=yourkey&data={"TaxCode":"14837428","Name":"","Status":""}
Recommended POST point query example:
POST https://listafirme.ro/api/info-v3.asp
Content-Type: application/x-www-form-urlencoded
key=yourkey&data={"TaxCode":"14837428","Name":"","Status":""}
Complete verified real-response example for an extended query:
{
"TaxCode": "14837428",
"RegNo": "J2002008118400",
"Status": "functiune",
"LegalForm": "SRL",
"Name": "BORG DESIGN SRL",
"NACE": "6210",
"NACERev": "3",
"PrincipalNACE": [
{
"Code": "6210",
"Rev": "3"
}
],
"Date": "2002-08-26",
"TownCode": "179187",
"County": "BUCURESTI",
"City": "SECTORUL 5",
"Address": "STR. ING. STEFAN HEPITES, Nr. 16A, Et. P, Cod 050196, ",
"Inactive": false,
"VAT": true,
"Administrators": [
{
"Name": "DIAC IUSTIN",
"Sex": "M",
"Nationality": "642",
"Position": "administrator",
"Active": true
}
],
"Shareholders": [
{
"Name": "DIAC IUSTIN",
"Sex": "M",
"Nationality": "642",
"Position": "asociat unic",
"Shares": "100"
}
],
"Balance": [
{
"Year": "2025",
"FixedAssets": "399947",
"CurrentAssets": "3009675",
"Turnover": "6174458",
"NetProfit": "677394",
"GrossProfit": "788880",
"Debts": "647115",
"EquityOwnership": "677781",
"Stocks": "97060",
"Cash": "2612273",
"Receivables": "300342",
"Income": "6344373",
"Outgoings": "5555493",
"AdvanceIncome": "2084726",
"AdvanceExpenses": "0",
"Employees": "26",
"NACE": "6210",
"NACERev": "3"
}
],
"Phone": [
"0213106793",
"0213106791"
],
"Mobile": [
"0730593252",
"0730593248"
],
"Email": [
"[email protected]"
],
"Web": [
"https://borgdesign.ro",
"https://listafirme.ro"
],
"Geolocation": {
"Lat": "44.40902",
"Lng": "26.09286",
"Approximated": false
},
"Description": "Borg Design este o companie cu capital privat ale cărei principale activităţi sunt dezvoltarea şi distribuţia de software precum şi consultanţă in tehnologia informaţiei. În particular, preocupările Borg Design sunt orientate şi către Inteligenţa Artificială.\r\n\r\nSoftware-ul dezvoltat de Borg Design are la bază solicitările, indicaţiile şi sugestiile clienţilor, şi are ca utilitate posibilitatea rapidă şi automatizată de a accesa şi prelucra informaţii publice de interes general. Obiectivul Borg Design este de a colecţiona aceste informaţii şi a vi le pune la dispoziţie intr-o formă prelucrată, alături de unele unelte software care au ca scop economisirea timpului dumneavoastră de informare şi in special a costurilor.\r\n\r\nBorg Design şi-a inceput activitatea in septembrie 2003, a realizat pană in prezent mai multe colecţii de date cu informaţii de interes public şi unele unelte software populare:\r\n\r\n- CD-ul Lista Firme;\r\n- Asistent Financiar;\r\n- Expert Email Validator;\r\n- TVA Validator;\r\n- Programul Telefoane.\r\n\r\n",
"Trademarks": [
"BORG",
"ListaFirme",
"TOPUL FIRMELOR ACTIVE LF ListaFirme.ro România"
],
"Subsidiaries": "0",
"Branches": "1",
"WorkLocations": [
{
"County": "BUCURESTI",
"City": "BUCURESTI SECTORUL 5",
"Address": "STR. STEFAN HEPITES, NR. 16A"
}
],
"SEAPPublicTenders": false,
"SEAPDirectSales": true,
"Links": [
{
"TaxCode": "18464976",
"Name": "LISTA FIRMELOR ACTIVE SRL"
},
{
"TaxCode": "26743262",
"Name": "BORG SOFTWARE SRL"
},
{
"TaxCode": "46604013",
"Name": "LISTA FIRMELOR ACTIVE FILIALA BUCURESTI SRL"
}
],
"cost": "0.00",
"credits": "3243.99"
}
Reference sets, security and errors
Usage recommendations, reference sets and possible error messages.
Reference sets:
- citizenships and nationalities use the ISO 3166-1;
- locality codes follow the SIRUTA;
- fields of activity follow the CAEN, and the revision of the returned code is indicated separately.
Attention: Use the API key only in your own applications or on the server. Using it in the browser (client side) exposes the secret key to other users. In production, use the POST method because GET, although accepted for testing, may expose the API key in logs and traffic statistics.
For POST requests, parameters are sent as regular request parameters, for example in application/x-www-form-urlencoded format. Sending a raw JSON body with Content-Type application/json is not documented as an input format for the current endpoints and must not be assumed to be supported.
For integration, we recommend a connection timeout of about 5 seconds and a total timeout of 30 seconds per request.
You can view or track in the log which IPs issued queries and how many were made, and if needed you can request a secret key reset. We also recommend restricting the IPs from which the service can be accessed.
API v3 applies two separate limits. The dynamic rate limit is up to 100 requests per second. Separately, a maximum of 8 requests may be active simultaneously for the same API account, shared across the info-v3 and search-v3 endpoints. Even when the rate is below 100 requests per second, a request exceeding the concurrency limit returns API_BUSY_RETRY and is not charged. For concurrent integrations, we recommend a local queue, no more than 8 active requests, and retrying rejected requests after a short delay with exponential backoff and jitter.
Every response has HTTP status 200. In case of an error, the response includes a stable code in the errorCode field and a descriptive message in the error field:
{
"errorCode": "STRING_CONSTANT",
"error": "mesaj descriptiv"
}
The practical difference between authentication errors and access errors is important: a missing, too short, or formally invalid API key returns INVALID_API_KEY, while a correctly formatted key without an active associated plan returns ACCESS_PLAN_REQUIRED for info-v3 and SEARCH_ACCESS_PLAN_REQUIRED for search-v3.
For TaxCode, INVALID_TAX_CODE means the transmitted value is not a syntactically valid VAT number, while TAX_CODE_NOT_FOUND means the value is syntactically valid but was not found in the queried database.
API_BUSY_RETRY is a transient error: the account already has 8 requests active simultaneously, or billing is temporarily busy with another request from the same account. The response retains HTTP status 200, the rejected request consumes no credits, and it may be retried in a controlled manner.
Automatic retrying is recommended only for transient network errors, timeouts or temporary throttling. Do not automatically retry requests that fail for functional reasons, such as an invalid key, missing active plan, invalid parameters or a non-existent VAT number. For network or throttling issues, we recommend at most 1-2 retries, with exponential backoff and jitter.
- INVALID_JSON_DATA = JSON data is invalid
- ACCESS_DENIED_IP = Access denied from IP ...
- ACCESS_PLAN_REQUIRED = A valid access plan is required
- SEARCH_STRING_TOO_SHORT = Search string should be at least 3 chars length
- TAX_CODE_NOT_FOUND = Tax code not found
- INVALID_TAX_CODE = Invalid tax code
- TAX_CODE_MISSING = Tax code is missing ...
- NOTHING_REQUESTED = Nothing requested
- DATA_MISSING = Data is missing
- INVALID_API_KEY = API key ... is invalid
- SEARCH_ACCESS_PLAN_REQUIRED = A valid access plan is required for this type of search
- SEARCH_EXTENDED_NOT_INCLUDED = Extended search is not included in access plan ...
- SEARCH_ADVANCED_NOT_INCLUDED = Advanced search is not included in access plan ...
- API_BUSY_RETRY = Too many simultaneous API requests for this account. Please retry shortly / API billing is busy for this account. Please retry shortly
For help integrating the API into your own applications, you may contact dezvoltatori.
Existing implementation examples (v3 material, updated for cost, credits, errorCode and the differences versus v2). Angular, .NET, Python, Java, React.
For AI systems and chatbots:
Do not expose the API key in public clients.
Differences between API v2 and API v3
Functional differences and recommendations for migrating to API v3.
-
Search (lookup by name/VAT No./Reg. No.):
- v2: The first 50 were free, then each additional search consumed one credit, with reset after point info queries.
- v3: Each search costs a fixed 0.02 credits and is charged fractionally.
- v3: The documentation explains simple search, extended search and advanced search separately, including the accepted prefixes for explicit criteria and the commercial conditions for using them.
-
Info (point queries):
- v2: The final cost was rounded up to the next whole credit.
- v3: The final cost is charged exactly, with two decimals, without rounding up to a whole credit.
- v3: Description is returned as plain text, not as HTML.
-
Balance and JSON response:
- v2: The response exposed the views field.
- v3: The response exposes the credits field as a decimal string with two decimals.
- v3: Error responses also expose the errorCode field, in addition to the error message.
-
Logical JSON types:
- v3: Logical fields are returned as real JSON booleans, for example VAT, ContactPerson.Active, Administrators[].Active, Geolocation.Approximated and FiscalActivity.History.
-
NACE / CAEN:
- v2: The documentation treated NACE as Rev.2 and did not explicitly expose the revision of the returned code.
- v3: It returns the current code from the companies table plus the NACERev revision, and in Balance it returns the historical code for that year plus its revision.
-
Charging mechanism:
- v2: It consumed only whole credits from active plans.
- v3: It uses whole credits from plans plus a fractional balance, and the remaining decimal part is kept for future queries.
-
Consumption tracking:
- v3: In consumption logging, only the actual whole-number decrement is stored; if consumption came only from the fractional balance, no whole-number decrease is recorded.
Minimum code changes for moving from v2 to v3
For a fast migration focused strictly on avoiding integration errors, the following adjustments are sufficient:
- Update the endpoints in use: replace calls to /api/info-v2.asp and /api/search-v2.asp with their corresponding v3 versions.
- Update the parsing of the remaining balance: in the JSON response, the views field is replaced by credits.
- Treat cost as a decimal string: in v3, the cost field is returned as text with two decimals, for both info and search.
- Parse the stable error code as well: in v3, error responses include the errorCode field in addition to the error message.
- Update logical types: in v3, logical fields are returned as real JSON booleans, not as strings.
- Update NACE parsing if you use the info value: in this case, NACE is no longer a string but an object with the properties Code , DescriptionRO and DescriptionEN; the revision is available separately in NACERev.
- Allow the new revision fields in JSON models: if you strictly validate the response schema, allow NACERev at response level and Balance[].NACERev in the Balance list.
- Stop treating Description as HTML: in v3 this field is returned as plain text.
- Update parsing of the search response: in v3, the Results key is always an array, and the hasMore key shows whether additional results existed beyond the limit of 50.
- Do not rigidly validate the response only against the current fields: over time, new compatible fields or options may appear, and the client application should ignore unknown fields instead of treating the response as invalid.
- There is no need to rewrite existing JSON requests for info: in most cases, the request structure used in info v2 remains valid in v3; adjustments are mainly needed in response parsing.
Recommendations for users
Migrating to v3 requires code changes see the differences above.
Choose v3 especially if you are aiming for one or more of the benefits below:
- exact charging, with better control over small or repetitive costs and a lower total cost.
- a balance that is easier to track in the application: the credits field is decimal, and cost is explicitly exposed with two decimals for each query.
- more robust integrations: error responses include errorCode , search-v3 always returns Results as an array, and hasMore explicitly signals truncation beyond the 50-result limit.
- more flexibility when identifying companies: besides name, VAT number or registration number, you can also search by website, email, phone, mobile or explicit criteria such as administrator, shareholder, locality, county, NACE code, description or former name, when the active plan includes the required options.
- more natural responses for modern applications and AI systems: logical fields are real JSON booleans, and Description is plain text, without HTML.
The version is explicitly included in v3 endpoints, and this is the current stable version. Incompatible changes will be published in a new major version, while compatible extensions may introduce new fields or options over time without changing the existing endpoint.
For long-term compatibility, write clients so they ignore unknown fields and treat the schema as extensible. API v2 remains active until December 31, 2026 to allow gradual migration, and starting January 1, 2027 its operation is no longer guaranteed.
Keep it secure: Use the API key only on the server, not in the browser.