Commercial API

Our Commercial API for CNPJ lookup provides real-time access to Federal Revenue Service, Simples Nacional, Taxpayer Registry, and SUFRAMA services. Through it, you obtain complete data about companies and establishments — registration status, address, emails, phone numbers, economic activities, shareholder structure, tax regime, state registrations, among others.

Additionally, there are advanced business intelligence tools such as PDF certificate issuance, precise geolocation, and aerial map and street view visualization.

This guide objectively describes the API’s resources, allowing you to perform lookups in a few minutes. For more details, see the API Reference .

Authentication

To perform a lookup, you must include your API Key in the Authorization header. This key is automatically generated when you register on our platform and consists of a 73-character string.

The absence of a valid key will result in an error in the API response:

To view your key, go to the API Key page.

Usage Limits

The use of our API is controlled by two factors:

• Credits: Consumed with each online query performed.
• Usage Limit: The per-minute rate at which you can make requests.

When credits are insufficient, the response is:

Upon exceeding the permitted number of queries per minute, you will receive:

Credits and usage limits are tied to the plan you have purchased. For more details, visit the Subscription page.

Federal Revenue

This lookup returns establishment registration data, such as registration status, address, contacts, economic activities, and shareholder structure.

Example of a lookup using our test CNPJ 37335118000180:

Response (simplified JSON):

Simples Nacional

The Federal Revenue lookup does not include information about the tax regime (Simples Nacional or MEI), as this data is obtained from different sources and incurs additional automation costs, consuming more credits.

To include Simples Nacional and MEI information, just add ?simples=true:

In the response, Simples and SIMEI information appears under company.simples and company.simei:

Taxpayer Registry

To obtain a company’s State Registrations, we use the Centralized Taxpayer Registry (CCC) or SINTEGRA, depending on whether or not there are GOV.BR credentials registered in the account. This service also involves an additional credit cost.

Simply include the parameter registrations=ORIGIN to retrieve registrations from the same state as the establishment’s origin:

Example response:

If you wish to query all states, replace ORIGIN with ALL. To specify particular states, separate them with commas, as in the example: registrations=PR,RS,SC.

SUFRAMA

The Superintendence of the Manaus Free Trade Zone (SUFRAMA) makes it possible to check the projects associated with the CNPJ, as well as the tax incentives granted. To obtain this data, just add suframa=true to your request.

Example of a lookup for CNPJ 04337168000148:

Simplified response:

Certificates

We offer several registration certificates, which are issued in real time at the moment of your request.

Federal Revenue

Members (QSA)

Simples Nacional

CCC

SUFRAMA

Geocoding

Add geocoding=true to the lookup to retrieve latitude and longitude coordinates, allowing you to display the establishment on a map or perform spatial analyses:

Example response:

Aerial Map

To view the establishment location in an aerial format, use the /map endpoint. The response will be a PNG image of the location:

The resulting file will be a PNG:

Street View

Street view allows you to observe the exterior of the establishment and surroundings. To do this, use the /street endpoint:

The resulting file will be a PNG:

Caching Strategies

Many features of our API can be queried in real time or by taking advantage of data stored in our cache. This helps reduce credit consumption and improve response time, without compromising the quality of the information in your application.

The primary purpose of the cache is to avoid unnecessary online requests. If the data found in our database is still considered up to date, your application can use it immediately. This reduces costs and latency, especially in applications that make recurring queries to the same CNPJs.

However, if the cached information is too old, the API may perform a real-time (online) query to ensure you have recent data. In addition, when there are failures in the online lookup, it is possible to return old data if it is within an acceptable timeframe, ensuring that your application continues to operate.

Configuration

The strategy parameter defines how the API decides between using cached data or performing an online query. The available options are:

• CACHE
  Returns only cached data. If there is no data stored in our database, the API returns a 404 error. No credits are charged, as no online lookup is performed.

• CACHE_IF_FRESH
  Returns cached data if it is within the update period defined by maxAge. If the cache is expired, it performs a new online query, resulting in credit consumption.

• CACHE_IF_ERROR (default)
  Behaves like CACHE_IF_FRESH, but if an online lookup fails, it will return cached data (even if expired for maxAge) if it is still within the maxStale period.

• ONLINE
  Performs the lookup directly at the source, without using the cache. Generally not recommended due to higher credit consumption. In situations where you need the most up-to-date information, you can substitute this approach with CACHE_IF_FRESH and maxAge=1, obtaining practically real-time data, but still with some degree of protection against failures.

Maximum Age

The maxAge parameter defines, in days, the maximum period for which cached data is considered valid before it is considered out of date. If the cache exceeds this period, the API attempts an online lookup.

• Default: 45 days
• It is used along with the CACHE_IF_FRESH and CACHE_IF_ERROR strategies.

Maximum Stale for Failures

The maxStale parameter determines, in days, how long after maxAge the data can still be returned if the online lookup fails.

• Default: 365 days
• It only takes effect with the CACHE_IF_ERROR strategy.
• By using maxStale, if the cache is old but within the defined period, the API will still return this data if an online error occurs. In this case, the response will contain "stale": true.

Practical Examples

• strategy=CACHE
  The API will only return data if it is cached. If no data is cached or it is older than 15 days, a 404 is returned. No credits are consumed.

• strategy=CACHE_IF_FRESH&maxAge=7
  Immediately returns if the cache is up to 7 days old. Otherwise, it will attempt an online lookup, consuming credits.

• strategy=CACHE_IF_ERROR&maxAge=7&maxStale=30
  Returns cache if it is up to 7 days old. If it is older, an online lookup is performed. In case of an online failure, it returns cache up to 30 days old and adds "stale": true to the JSON.

• strategy=ONLINE
  Ignores the cache and always performs an online lookup (high credit consumption). Alternatively, you could use strategy=CACHE_IF_FRESH&maxAge=1 to have almost real-time data, but without wasting credits if there is a very recent cache (under 1 day).

Observations

• The ONLINE option can increase costs, as each attempt triggers a request to the official source.
• In high-criticality situations or when information needs to be updated more frequently, lower maxAge values may be configured, but be mindful of the impact on your credits.
• To know which services support caching, see the Subscription page.

Final Considerations

With this guide, you should be able to perform the main queries in a few minutes, leveraging registration, tax, geographic, and visual information to support your business decisions and workflows.

If you need more details about each returned field, see the API Reference .

If you have any questions or difficulties, we are here to help!