← Back to AAI for MerusCase

Find Contact

The firm-wide name lookup. Type a doctor’s name, an adjuster’s name, an opposing counsel’s name, and the skill returns every case that contact is linked to with phone, email, and role. Unicode-normalized matching handles the apostrophes, hyphens, accents, and prefixes that break naive search — the kind of edge cases that, when missed, end with a paralegal creating a duplicate contact in Merus.

The names, phone numbers, and case references in this page are fictitious demonstration data. Your install runs against your real contacts.

On this page

What it is

At the prompt:

aaicase> find Dr. Sample
aaicase> find contact Sample
aaicase> who is the adjuster for Sample Insurance
aaicase> find Sample Adjuster across all cases

About ten seconds later you have the list of matching contacts with their phone, email, and every case in the firm where they appear as a party. The most common use is “I need to call Dr. Sample but I’m not on her case file right now” — this is the skill that surfaces her contact info without making you open six cases looking for it.

How it runs (under the hood)

Two API calls maximum:

/contacts/index           → all firm contacts (lightweight: last + first only)
/contacts/view/[CONTACT-ID] → full detail for each match (Party data, phones, addresses)

The index endpoint returns a slim record per contact — just the names — so the initial search is fast. For each match the skill follows up with a per-contact view to pick up phones, emails, addresses, and (most importantly) the Party data that lists every case the contact is linked to.

If a search returns 20+ matches, the skill caps the per-contact detail fetches at the top 20 to keep the run under 15 seconds. Wider searches show the remaining count (“... and 14 more — refine your search”).

Name normalization — why O’Brien matches obrien

Naive substring search on firm contacts misses the names that actually exist in legal practice. Apostrophes, hyphens, accents, dots, spaces — all the punctuation that real names use is the punctuation that breaks “does the contact’s last name contain my search term?”

The skill normalizes both the contact’s name and the search term identically before comparing, using the same normalization rule that lives in lib/binding.mjs and merus-search.mjs:

norm = str => str
  .normalize('NFD')         // decompose accented chars
  .replace(/[̀-ͯ]/g, '')     // strip combining marks
  .toLowerCase()
  .replace(/[^a-z0-9]/g, '') // strip everything but alphanumerics

So:

A search for “obrien” matches all of O’Brien, Obrien, and even O’ Brien (with a stray space). A search for “nunez” matches Núñez and Nunez without requiring the attorney to type the accent.

This is the same normalizer used in process mail’s binding logic and audit case’s filename verification — shared across the codebase so name matching is consistent everywhere AAI looks for a person.

Match shapes — first, last, first+last

The match check tries four shapes for each contact:

  1. last.includes(query)
  2. first.includes(query)
  3. (last + first).includes(query) — catches “samplesara” for Sample, Sara
  4. (first + last).includes(query) — catches “sarasample” the same way

This means the attorney can search “Sample” (last), “Sara” (first), “sample sara” (typed out without thinking about which is first/last), or “Dr. Sara Sample” (with prefix) — all four return the same contact.

It also means the attorney can search by initials (“SS” for Sara Sample) by typing “ss” — the substring match against the concatenated name will hit. This is less reliable than full-name search and the skill notes it — for ambiguous short queries (1–2 characters), the skill asks for more.

Per-contact: which cases is this person on?

The most valuable part of the output is the “cases linked” line under each match. The skill pulls the Party data from the contact’s view, which lists every case the contact is on with case_file_id and current case_status_id.

So if Dr. Sample is the PTP on six cases and the QME on four, the output shows all ten cases — with case name, file number, and status. The attorney can then open any one of them directly.

This is the highest-leverage part of the skill for medical-legal practice. A treating provider often spans many of the firm’s cases; an adjuster from a large carrier may appear on dozens. Surfacing all of them at once turns “which case was Dr. Sample on?” into a list.

Duplicate detection

If the search returns two contacts with the same normalized name (e.g. Garcia, Maria at contact ID 1001 and Maria García at contact ID 2042), the skill flags it explicitly:

⚠ Possible duplicate: two contacts match “garciamaria”. Check whether these are the same person and merge in Merus.

Duplicates are a common source of confusion — a doctor entered twice means activities, lien letters, and party links may split across two records. The skill surfaces the suspect duplicates so the firm can clean them up; it doesn’t attempt to merge automatically (that’s an attorney-level decision about which contact record is canonical).

Example output

CONTACT SEARCH — "sample"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3 contacts matching:

1. Sample, Sara (Dr.) — Contact ID [#]
   Phone:    (555) 555-0166
   Email:    sara.sample@example.com
   Address:  123 Sample Way, Anaheim, CA
   Specialty: Orthopedic Surgery (PTP, QME panel)

   Cases linked (8):
     Doe, Jane v. Sample Co.       (#[FILE-#])  Open    [PTP]
     Roe, Maria v. Sample Inc.     (#[FILE-#])  Open    [QME]
     Sample, Alex v. Sample Dist.  (#[FILE-#])  Settled [PTP]
     [...5 more]

2. Sample, John (Adjuster) — Contact ID [#]
   Phone:    (555) 555-0177 ext. 3214
   Email:    j.sample@sampleinsurance.com

   Cases linked (4):
     Doe, John v. Sample Foods    (#[FILE-#])  Open    [Adjuster]
     [...3 more]

3. Sample Insurance Co. (Carrier) — Contact ID [#]
   Phone:    (555) 555-0188
   Email:    claims@sampleinsurance.com

   Cases linked (12):
     [...all 12 listed]

NEXT STEPS:
  1. Want to call Dr. Sample? Phone: (555) 555-0166
  2. Want to see the full party history? Open any case above

When to run it

Troubleshooting

“No contacts matching X” but I know they’re in Merus

Most often the name in Merus uses different punctuation than your search — Mc Donald with a space vs. McDonald without. The normalizer should handle this; if it doesn’t, the contact may be entered with a typo in Merus. Try searching by the first name alone, or by the phone number area.

Too many matches

Common with carrier names — “Sample” might match 80 contacts at a firm that does a lot of work against Sample Insurance. Use a more specific search term, or include a partial first name (“sample j” to narrow to Sample, John).

The cases-linked list is incomplete

The skill pulls Party data from the contact view. If a contact is associated with a case via an activity instead of a Party (some firms link providers via activities only), the case won’t show in the party list. Run audit case if you suspect an upload is on a case where the provider isn’t formally a party.

I want to search by phone number or email, not name

As of 4.5.508, that’s a separate skill: Search Contacts. It does a two-phase search — the flat /contacts/index sweep PLUS a deep walk of /caseFiles/view/N records that surfaces phones and emails living on applicant, employer, witness, or carrier sub-records (the fields this skill’s flat index does not carry). Trigger phrases include “find by phone”, “look up phone X”, “case for [number]”, “find email Y”.

The duplicate flag fired but the two contacts are clearly different people

Same normalized name, different actual people — common with common names (“Garcia, Maria” could be two unrelated people). The skill flags possible duplicates; the attorney decides. Don’t merge unless they’re the same person.

Part of AAI for MerusCase — code-guarded AI case intelligence for California Workers’ Comp attorneys.