# SearchContactsByContactNameAndAKA - Advanced Documentation

## Search Strategy

**Use short partial names for broader matching.** Searching `"joh zip"` will match more results than `"johnny zippy"`. Shorter prefixes are more tolerant of spelling variations and name formats.

**Multiple contacts may share a name.** Always iterate ALL returned contacts, not just the first one. Different people can have the same or similar names - never assume the first result is the right one.

## Cross-Reference Patterns

When you need to find what claims a person is associated with, search for contacts then call `GetRelatedClaims` for **each** matching contact:

```javascript
async () => {
  // Use short partial name for broader matching
  const contacts = await SecureApi.SearchContactsByContactNameAndAKA("bob tig");
  if (!contacts.length) return { error: "No contacts found" };

  // Iterate ALL contacts - multiple people may share a name
  const results = [];
  for (const contact of contacts) {
    const relatedClaims = await SecureApi.GetRelatedClaims(contact.ID);
    results.push({
      contact: { id: contact.ID, name: contact.Name, phone: contact.PrimaryPhone, email: contact.PrimaryEmail },
      claims: relatedClaims.map(rc => ({
        claimId: rc.Claim.ID, claimName: rc.Claim.Name,
        claimType: rc.Claim.Type.Name, status: rc.Claim.Status,
        role: rc.ContactType.Name
      }))
    });
  }
  return results;
}
```

To combine with a case name search (e.g., user mentions both a person and a case), use `Promise.all`:

```javascript
async () => {
  const [claims, contacts] = await Promise.all([
    // Claim names are LastName_FirstName - search by last name prefix
    SecureApi.SearchClaimsBySystemFieldString("Name", "Zippy"),
    SecureApi.SearchContactsByContactNameAndAKA("bob tig")
  ]);

  // Iterate ALL contacts - never assume the first is correct
  const allContactClaims = [];
  for (const contact of contacts) {
    const relatedClaims = await SecureApi.GetRelatedClaims(contact.ID);
    allContactClaims.push(...relatedClaims.map(rc => ({
      contactId: contact.ID, contactName: contact.Name,
      claimId: rc.Claim.ID, claimName: rc.Claim.Name,
      claimType: rc.Claim.Type.Name, role: rc.ContactType.Name
    })));
  }

  // Cross-reference: which claims match BOTH the case name and a contact
  const claimIds = new Set(claims.map(c => c.ID));
  const matches = allContactClaims.filter(rc => claimIds.has(rc.claimId));
  return { allClaims: claims.map(c => ({ id: c.ID, name: c.Name })), matches };
}
```

**Key points:**
- `GetRelatedClaims(contactId)` returns all claims a contact is on, with their role (adjuster, claimant, witness, etc.)
- Use `Promise.all` to run independent searches in parallel
- Cross-reference by claim ID to find connections between people and cases
- Always iterate all contacts - never use `contacts[0]` without checking the rest

## Overview

Performs parallel async searches for contacts matching a filter string against both primary display name and alternate/AKA names, combining results and deduplicating by contact ID. This is the primary endpoint for finding contacts by name. This document also covers the broader contact search ecosystem and when to use each endpoint.

## Which Endpoint to Use

| Scenario | Endpoint | Notes |
|----------|----------|-------|
| Have a ContactID already | `GetContactByID` | Direct lookup, no searching needed |
| Search by name (most common) | `SearchContactsByContactNameAndAKA` | Searches both display name and AKA names |
| Search by phone number | `SearchContactsByContactPhoneNumber` | Extracts digits, searches normalized phone |
| Search by email | `SearchContactsByContactEmail` | Searches email addresses |
| Search by address | `SearchContactsByContactAddress` | Searches single-line display address |
| Search by SSN | `SearchContactsByContactSSN` | Searches Social Security Number |
| Search by AKA only | `SearchContactsByContactAKA` | Searches alternate names only |
| Search by tags | `SearchContactsByContactTags` | Searches contact tag values |
| Search by date of birth | `SearchContactsByContactDOB` | Exact date match (not prefix) |
| Search by system field | `SearchContactsBySystemField` | Pass the field name |
| Search by ad-hoc field | `SearchContactsByContactAdhocField` | Requires AdHocFieldDefinitionID |
| Search contact documents | `SearchContactDocuments` | Multi-criteria document search |
| Browse/manage saved searches | `GetFirmAdvancedSearches` | Returns both claim and contact saved searches |
| Run a saved search | `GetAdvancedSearchResults` | Executes a saved advanced search query |

## Contact Name Formats

**Person contacts:** Display name is typically `LastName, FirstName` format. The system stores multiple name variants:
- `Name` - primary display name
- `DisplayName` - formatted display name
- `Name_FL` - FirstName LastName
- `Name_PFMLS` - Prefix FirstName MiddleName LastName Suffix
- `Name_PL` - Prefix LastName
- `Name_FMLS` - FirstName MiddleName LastName Suffix
- `Name_FML` - FirstName MiddleName LastName

**Company contacts:** Name is the company name directly.

## Name Search Behavior

- **FixPeopleFilter processing:** Input like `Doe, John` is reversed to `John Doe` for natural matching
- **Dual search:** Runs two parallel queries - one against display name, one against AKA names
- **Deduplication:** Results are merged and grouped by ContactID to remove duplicates
- **Prefix matching by default** (appends `%`)
- Callers can include `%` wildcards for flexible matching

## Wildcard Strategies for Name Searches

| Filter | What It Finds | Use Case |
|--------|---------------|----------|
| `Smith` | Contacts whose name starts with "Smith" | Quick prefix search |
| `%Smith` | Contacts with "Smith" anywhere in name | More inclusive, handles middle names |
| `%Smith%` | Same as above | Contains matching |
| `Jo%Smith` | "Jo..." then "Smith" somewhere after | Partial first + last name |
| `%Sm%` | Any contact with "Sm" anywhere | Misspelling-tolerant (catches Smith, Smithson, etc.) |

**Tip for misspellings:** Use shorter prefixes with `%` wildcards to be less restrictive. For example, `%Smi%` will catch "Smith", "Smithson", "Smit", etc. The shorter the prefix, the more results returned but the more tolerant of spelling variations.

## Searchable Contact System Fields

These are the valid `SystemFieldName` values for `SearchContactsBySystemField`:

| Field Name | Type | What It Searches |
|------------|------|-----------------|
| ID | Number | Contact ID |
| FirmID | Number | Company/firm ID |
| IsPerson | Boolean | Person vs. company flag |
| Prefix | String | Name prefix (Mr., Mrs., etc.) |
| FirstName | String | First name |
| LastName | String | Last name |
| MiddleName | String | Middle name |
| Name | String | Primary display name |
| DisplayName | String | Formatted display name |
| DateOfBirth | Date | Date of birth |
| DateOfDeath | Date | Date of death |
| SocialSecurityNumber | String | SSN |
| PreferredContactMethod | String | Preferred contact method |
| TaxNumber | String | Tax identification number |
| Suffix | String | Name suffix (Jr., Sr., etc.) |
| AKA | String | Also Known As / alternate names |
| WebSite | String | Website URL |
| RepresentationStatus | String | Representation status |
| Name_FL | String | FirstName LastName format |
| Name_PFMLS | String | Prefix First Middle Last Suffix |
| Name_PL | String | Prefix LastName |
| Name_FMLS | String | First Middle Last Suffix |
| Name_FML | String | First Middle Last |
| GlobalID | String | Global identifier |
| BirthMonth | String | Birth month |
| CreatedDate | Date | Record creation date |
| ContactPreferenceNotes | String | Contact preference notes |
| ReferredByContactID | Number | Referring contact ID |
| HowDidYouHearAboutUsOptionID | Number | Marketing source option |
| RepresentativeID | Number | Representative contact ID |
| AccountingExternalID | String | External accounting ID |
| AccountingExternalIDType | String | Accounting ID type |
| AccountingExternalIDName | String | Accounting ID name |
| RepresentativeTypeID | Number | Representative type |
| LanguageID | Number | Language preference |

## Filter Processing

The `FixPeopleFilter` function (used by name, AKA, SSN, and system field searches) processes input:
- Detects comma-separated input (e.g., `Doe, John`)
- Reverses the parts to `John Doe` for natural matching
- Trims whitespace

Filter length limits vary by endpoint:
- Most searches: **50 characters**
- Tags search: **100 characters**
- Ad-hoc field search: **200 characters**

## Security

All contact search endpoints enforce:
- User must be logged in
- User must have a company selected
- User must be a member of that company
- Results are scoped to the current company (FirmID filter)