How the Vigilant + Google Sheets integration works

TL;DR: Google Sheets + Google Apps Script + Vigilant API = automated lawsuit search directly in the spreadsheet, without leaving Google Workspace. The lawyer adds a CPF in the sheet, clicks “Search” (or schedules it to run weekly), and the cases appear in the rows below. Zero infrastructure, zero tool cost (Apps Script is free), API cost = R$ 0.10 per query. Practical limit: ~50-100 CPFs per execution. For larger volumes, scale to Make/n8n.

Google Sheets is one of the most-used tools in Brazilian law firms and compliance teams. Lawyers, interns, and analysts build spreadsheets to track client portfolios, deadlines, court fees — and, almost always, manually pasted lawsuit search results. This is one of several ways to automate lawsuit research in a law firm.

The problem: this research is still a manual process. The lawyer opens each court website, types the CPF, copies the result into the spreadsheet. Since the spreadsheet already exists and is part of the firm’s workflow, the natural question is: why not call the Vigilant API from within the spreadsheet itself?

This article explains the concept, when it makes sense to use this approach, and what decisions you need to make before starting. To understand the endpoints, schemas, and response formats you will consume, the official API documentation has the complete technical reference in curl, Python, and JavaScript — you adapt it to whatever environment you use.

Note for international readers: CPF is Brazil’s individual taxpayer ID. Every Brazilian court case references parties by CPF, and Vigilant’s API takes it as the primary search parameter.

The core idea

Google Sheets has a built-in scripting engine called Google Apps Script, which is JavaScript running in Google’s cloud, free, with direct access to spreadsheet cells. Apps Script can make outbound HTTP calls, so it can call the Vigilant API just like any other client.

This makes it possible to create custom functions that the lawyer uses like any native Sheets formula:

=SEARCH_CPF(A2, "TJSP,TJMG")

You type this formula into a cell, Apps Script calls the Vigilant API, receives the JSON with lawsuits, and returns a summary. The lawyer sees the case count appear in real time, without leaving the spreadsheet.

High-level architecture

[ Google Sheets spreadsheet ]
       │
       │ (custom formula =SEARCH_CPF)
       ↓
[ Apps Script (JavaScript) ]
       │
       │ HTTPS
       ↓
[ Vigilant API ]
       │
       ↓
[ Brazilian courts ]

Nothing more complex than that. The spreadsheet triggers the script, the script calls the API, the API returns JSON, the script extracts what matters and writes to the cell.

When this approach makes sense

This pattern is ideal when:

• Low to medium volume — up to ~500 searches per month. Above that, direct API use or a custom backend are more efficient.
• No technical team — does not require a developer. A lawyer with basic notions copies the official doc example and adapts.
• Spreadsheet-centric workflow — makes more sense to integrate into the tool the firm already uses than to force a process change.
• Ad-hoc or exploratory searches — lawyer pastes a list of prospect CPFs and quickly sees who has case history.

It does not make sense when:

• High volume (thousands of searches per month) — Apps Script has a 30-second execution limit for custom functions, and Google imposes daily external-fetch quotas.
• Workflow needs to be transactional — not production-grade SLA.
• Sensitive data — the API key lives in the Apps Script code and can leak if the spreadsheet is shared incorrectly.

Decisions you need to make upfront

1. Where to store the API key

The safest approach is to use PropertiesService in Apps Script, which stores the key outside the source code. Even if someone views the script, the key does not appear. The official API documentation explains the step-by-step.

2. Synchronous or asynchronous function

Vigilant returns cached results instantly (status 200) or starts a background job (status 202). For spreadsheets, the most comfortable approach is to use cache only: if the data is fresh, it returns immediately; if not, it returns “processing” and you re-run the formula later. This avoids timeouts inside Apps Script.

3. One cell = one CPF vs one cell = one court

You can structure the spreadsheet two ways:

• One row per CPF, with a summary cell per court: =SEARCH_CPF(A2, "TJSP"), =SEARCH_CPF(A2, "TJMG"), etc.
• One row per case found, using a function that returns multiple rows (Apps Script supports return arrays)

The first is simpler; the second is better for detailed analysis. Choose based on usage.

4. When to re-search

Apps Script does not re-execute formulas by itself unless you change a cell. If you want automatic updates (monitoring), use a time trigger that re-executes a function every Monday at 7 AM, for example. Then the spreadsheet becomes a small monitoring system — not an on-demand query.

Usage patterns in a law firm

New-client due diligence

A tab with a list of prospect CPFs. A column with the formula =SEARCH_CPF(cpf, courts). The lawyer pastes the CPFs, hits Enter, and in seconds sees who has case history — triage tool before accepting the case.

Active portfolio monitoring

List of active clients. Weekly trigger that re-searches all and compares with the previous total. If any client has new cases, sends an email to the responsible lawyer (Apps Script has native Gmail access).

Supplier triage

List of suppliers + partner CPFs. Monthly re-search. Alert if the case volume crosses a threshold.

Practical limits

• Timeout: Apps Script custom functions have a 30-second timeout. Searching 10+ courts can exceed this. Break into smaller calls.
• Daily quota: Google limits UrlFetchApp calls to 20,000/day on free accounts. More than enough for small and medium firms.
• Sharing: if you share the spreadsheet with edit permission, Apps Script runs with the owner’s credentials. Could be a problem for whoever pays, not for the key itself.
• Returned data: Vigilant’s JSON is large (parties, movements, subjects). Extract only what matters in the formula — do not paste the entire JSON into a cell.

When to migrate to something more robust

When you feel:

• Slowness in searches (frequent timeouts)
• Need for precise scheduling (not just “Monday 7 AM”, but “every day at 3 AM”)
• Historical storage (compare cases between executions, generate reports)
• Integration with other tools (CRM, Slack, firm ERP)

The natural evolution is to move out of Apps Script and use a visual automation tool (Make, n8n, Zapier) or a custom backend. But for 80% of cases, the spreadsheet solves it.

Legal aspects

Public court data has legal basis for processing under LGPD (Brazil’s GDPR equivalent — Art. 7, §4). No problem processing public consultation results inside a corporate firm spreadsheet, as long as the purpose is legitimate (client defense, risk management, compliance).

The API key is a sensitive asset of your firm (not of the CPF holder). Protect the key like a password — use PropertiesService, do not leave it exposed in shared spreadsheets.

API technical reference

The concrete implementation depends on the endpoints, schemas, and responses the API exposes. The official documentation is where this lives maintained and up-to-date:

• vigilant.trackjud.com.br/api/docs — interactive Scalar UI (English and Portuguese)

There you find: the authentication flow (how to get an API key), the format of each endpoint, response schemas (ProcessRecord, Consult, CourtSources), error codes per RFC 7807, and request examples in curl, Python, and JavaScript. From those base examples, you adapt to whatever environment you prefer — an Apps Script function, a Make workflow, or a custom backend.

Conclusion

Integrating Vigilant with Google Sheets is a realistic shortcut for firms that already have their workflow centralized in a spreadsheet and want to eliminate the manual part of the research. The complexity is low, the return is immediate, and the scale ceiling (Apps Script) is enough for most small and medium firms.

If you fit that profile, start with the most painful use case (usually new-client triage or portfolio monitoring), build a small proof-of-concept spreadsheet, validate, and expand.

5 free credits on sign-up. No credit card. Create a Vigilant account.