find-law-firm

find-law-firm

Drive the ServiceGraph API (https://api.servicegraph.co) to find, shortlist, and enrich US business-to-business law firms via the pro_services dataset.

The catalog is B2B-only. A historical audit dropped over half of high-rank "legal" firms because they served personal/consumer matters (divorce, personal injury, criminal defense, family law, estate planning). The remaining catalog skews toward corporate, IP, M&A, securities, employment, commercial litigation, regulatory, data privacy, real-estate transactions, and corporate tax.

Always pin industry:legal. Sub-areas of law are NOT separate tags — industry:legal is the most specific structured level — so practice-area specialization (IP, M&A, employment, securities, etc.) is a keyword substring search on firm text.

Any HTTP client works (curl, fetch, requests). Examples below use curl.

When NOT to use this skill

The single biggest failure mode is firing on consumer-personal legal asks. Refuse those — don't fall back to a partial filter.

• Personal/family matters where the user is the end client: divorce, child custody, family law, estate planning, wills/trusts, personal injury, criminal defense, individual bankruptcy, immigration for the user themselves, landlord/tenant disputes.
• DIY legal research: "is this enforceable?", "do I owe…?", "what does this clause mean?".
• In-house counsel hires (GC, paralegal, contracts manager).
• Non-US firms / individual freelancers / contract attorneys.

MCP server (preferred for authed calls)

If your harness has the ServiceGraph MCP server loaded (tools containing servicegraph), prefer those — OAuth 2.1 + PKCE keeps the token in the harness sandbox. Otherwise use the REST flow below.

API surface (dataset id: pro_services)

Every endpoint requires the bearer (Authorization: Bearer vk_…). No anonymous tier.

| Endpoint | Cost | Use it for | |---|---|---| | GET /v1/datasets/pro_services/fields[?include_values=1] | free | Confirm legal is in the industry value list. | | GET /v1/datasets/pro_services/check?filter=… | free | Validate filter. | | POST /v1/datasets/pro_services/translate-intent | free | {intent} → DSL filter + sanity count. | | GET /v1/datasets/pro_services/search?filter=…&limit= | free | Brief firm cards + per-row unlock hint + total. | | GET /v1/datasets/pro_services/:apex | free | One row brief; detail only if unlocked. | | POST /v1/datasets/pro_services/unlocks | 10 credits / firm | {apexes:[...]} ≤100; atomic; 30-day TTL on detail. | | GET /v1/me/credits | free | Balance. |

Cost model. Discovery / validation / search / brief reads are free. Detail (url, phone, email, social, address, full platforms map) costs 10 credits per firm and lasts 30 days.

Note: service_provided tags are not populated for industry:legal in the current catalog (Clutch and similar directories don't break legal down further). Use barewords for practice areas.

Auth

vk_* API keys minted in the dashboard. Keep the token out of the LLM context — never read .env* into your context; dispatch via shell.

1. Try the call first through a shell wrapper that sources .env.local:

``bash ( set -a; [ -f .env.local ] && . ./.env.local; set +a; curl -sS -H "Authorization: Bearer $SERVICEGRAPH_API_KEY" \ 'https://api.servicegraph.co/v1/datasets/pro_services/fields' ) ``

1. On 401 prompt the user:

"Open https://servicegraph.co/profile/api-keys, create a key, and add SERVICEGRAPH_API_KEY=vk_… to .env.local here (or export it). Tell me when done. Please don't paste the key into chat."

1. Retry after the user signals ready.

Filter DSL

GitHub-search-style.

filter   := orExpr
orExpr   := andExpr ("OR" andExpr)*
andExpr  := notExpr (("AND")? notExpr)*    # whitespace = implicit AND
notExpr  := ("NOT" | "-") notExpr | atom
atom     := "(" filter ")" | predicate
predicate:= IDENT op valueOrList | bareword
op       := ":" | "=" | ">=" | "<=" | ">" | "<"
valueOrList := value ("," value)*
value    := IDENT | NUMBER | tagAtEvidence
tagAtEvidence := IDENT "@" ("low"|"medium"|"high")
bareword := IDENT | NUMBER          # → keyword:<bareword>

Four rules that bite: AND binds tighter than OR (use parens); comma list = OR within one predicate; negation is -x or NOT x; bareword = keyword search (quote multi-word phrases).

Legal-flavored examples (validate yours with /check):

industry:legal state:CA patent
industry:legal state:NY,DE m&a
industry:legal employment
industry:legal securities ipo
industry:legal "data privacy" gdpr
industry:legal "commercial litigation" state:TX
industry:legal -company_size_signal:solo rating>=4 review_count_total>=20
industry:legal corporate startup

Practice area → keyword mapping (sub-areas are not structured tags):

| User asks for | Add as keyword(s) | |---|---| | IP / patents / trademarks | patent, trademark, ip | | M&A / mergers and acquisitions | m&a | | Securities / IPO / capital markets | securities, ipo | | Employment law (employer-side) | employment, labor | | Commercial litigation / disputes | litigation, commercial | | Regulatory / compliance | regulatory, compliance | | Data privacy / cyber / GDPR / CCPA | privacy, gdpr, ccpa, cyber | | Real estate (commercial) | "real estate", "commercial real estate" | | Tax (corporate) | tax | | Corporate / formation / governance | corporate, formation, governance | | Antitrust | antitrust | | Bankruptcy (corporate) | bankruptcy | | Immigration (corporate sponsorship) | immigration |

Identifying firms — apex

Firms are identified by their apex domain (dlapiper.com, not www.dlapiper.com/about).

Recipes

A. IP / patent firm in a state

User: "Three boutique IP law firms in California for hardware-startup patent prosecution."

GET /v1/datasets/pro_services/search?filter=industry:legal+state:CA+patent+-company_size_signal:large_50plus&limit=10
# Present, get pick of 3. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }

B. M&A counsel for a fundraise

GET /v1/datasets/pro_services/search?filter=industry:legal+state:NY+m&a&limit=10

C. Securities / IPO experience

GET /v1/datasets/pro_services/search?filter=industry:legal+securities+ipo&limit=10

D. Indirect intent — "outside counsel for GDPR/SOC2"

User: "Our compliance is getting complex — we need outside counsel for GDPR, CCPA, and SOC2 oversight."

GET /v1/datasets/pro_services/search?filter=industry:legal+(gdpr OR ccpa OR privacy)+compliance&limit=10

Or use the intent translator:

POST /v1/datasets/pro_services/translate-intent
  { "intent": "outside counsel for GDPR/CCPA compliance and SOC2 oversight" }

E. Employment law for a tech employer

GET /v1/datasets/pro_services/search?filter=industry:legal+employment+tech+company_size_signal:medium_10_50,small_2_10&limit=10

F. Quality threshold + commercial litigation

GET /v1/datasets/pro_services/search?filter=industry:legal+commercial+litigation+state:TX+rating>=4&limit=10

G. BYO apex list — enrich domains

User pastes 8–20 law-firm domains:

1. GET /v1/datasets/pro_services/:apex per domain — free brief (404 = not in catalog, no charge). A 404 often means the firm is consumer-focused (divorce, PI) and was filtered out of the B2B catalog.
2. User picks N to fully enrich. POST /unlocks = 10×N credits, atomic, detail returned.
3. Re-runs within 30-day TTL are free.

Gotchas

• Always pin industry:legal. Without it, "patent" or "m&a" as keywords leak into marketing/IT meta tags.
• Refuse consumer-personal legal asks. Divorce, personal injury, criminal defense, family law, estate planning, wills, individual immigration, personal bankruptcy — NOT in the catalog. Tell the user the catalog is B2B-only and suggest elsewhere (state bar referral, Avvo). Do NOT return a partial result hoping it's close enough.
• industry:legal is the only structured handle. Practice areas are keyword-only. Multi-word areas split into ANDed barewords unless quoted ("commercial litigation" → one phrase).
• Catalog skews toward mid/large B2B firms. Solo practitioners and <5-attorney shops are under-represented. For "boutique", exclude company_size_signal:large_50plus rather than requiring solo.
• DIY/legal-research questions ("is this NDA enforceable?", "explain fair use") are NOT procurement.
• Software-product comparisons (Ironclad vs DocuSign) are NOT procurement.
• Briefs DO include apex, name, location, ratings. They DON'T include url, phone_primary, email_primary, legal_name, address_full, full platforms — those require an unlock.
• not_found / not_in_dataset 404 = not in pro_services. Skip; not charged.
• Unlock is atomic. N apexes either all charge (up to 10×N credits) or none on 402.
• Within-TTL re-views are free (was_cached:true).

Errors

JSON envelope: {"error": {"code": "...", "message": "..."}}.

| Status | Code | What to do | |---|---|---| | 400 | filter_parse_error | position included; fix and re-validate with /check. | | 400 | kind_in_filter | Strip any kind: from filter. | | 400 | field_not_in_dataset | Drop the disallowed field. | | 400 | invalid_apex | Re-normalize. | | 401 | unauthorized / invalid_audience | Re-prompt for fresh vk_…. | | 402 | insufficient_credits | needed and balance; nothing charged. | | 404 | not_found / not_in_dataset | Skip; not charged. | | 429 | rate_limited | Honor Retry-After. |

End-to-end example

User: "Three boutique IP law firms in California that handle patent prosecution for hardware startups, ideally with at least a 4-star rating."

GET /v1/datasets/pro_services/fields?include_values=1
GET /v1/datasets/pro_services/check?filter=industry:legal+state:CA+patent+rating>=4+-company_size_signal:large_50plus
GET /v1/datasets/pro_services/search?filter=...&limit=10
# Present briefs. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }
GET /v1/me/credits