# SearchClaimsExtended - Advanced Documentation

## When to Use

**Individual claim lookup only.** Returns max 10 records. Do NOT use for bulk, aggregate, or "all claims" queries - use Advanced Searches instead (`GetFirmAdvancedSearchesClaim` to find a saved search, then `GetAdvancedSearchResults` to execute it).

## Search Behavior

The filter matches against BOTH the auto-generated claim name AND the claimant display name simultaneously (OR logic):
- **Claim names** are auto-generated with truncated, underscore-joined parts: a person claimant named `FirstName LastName` produces `LastNa_FirstN_{ClaimTypeAbbreviation first 6}_{ClaimID}`; a company claimant named `Company Name` produces `CompanyName_{ClaimTypeAbbreviation first 6}_{ClaimID}`
- **Claimant names** are the contact display name

### Filter Processing
1. Filter is cleaned (trimmed, special chars handled)
2. `FixPeopleFilter` reverses comma-separated input (`Doe, John` becomes `John Doe`)
3. Prefix matching by default (appends `%`)
4. Callers can include `%` wildcards for contains/suffix matching

### Date Detection
If the filter parses as a valid date with year > 1900, the search switches to **incident date matching** instead of name matching.

## Wildcard Strategies

| Filter | What It Finds | Use Case |
|--------|---------------|----------|
| `Smith` | Claims with name or claimant starting with "Smith" | Quick lookup |
| `%Smith` | "Smith" anywhere in name or claimant | More inclusive |
| `Smith%PI` | Names starting with "Smith" containing "PI" | Name + type |
| `771360` | Claims with ID containing "771360" in the name | ID-based search |
| `03/15/2025` | Claims with incident date 3/15/2025 | Date search (auto-detected) |

## What's NOT Returned

- **Closed claims** are excluded from results
- **Full claim data** is not included - only summary fields (ID, Name, Status, IncidentDate, ClaimType, Claimant info, Timestamp)
- No notes, documents, staff, ledger entries, or ad hoc fields

## Security

Results are filtered by the caller's claim security permissions. Private claims the user cannot access are excluded from results.

## Script Example

```javascript
async () => {
  // Search by name
  const results = await SecureApi.SearchClaimsExtended("Smith");
  return results.Data.map(c => ({
    id: c.ID,
    name: c.Name,
    status: c.Status,
    type: c.ClaimTypeIDName,
    claimant: c.ClaimantIDDisplayName
  }));
}
```

## Usage Example

Pass a plain string - the claimant's name or partial name. Do NOT pass an object.

```javascript
// CORRECT - plain string argument
const results = await SecureApi.SearchClaimsExtended("FirstName LastName");
const claimId = results.Data[0].ID;

// WRONG - any object format causes HTTP 500
// WRONG: SecureApi.SearchClaimsExtended({SearchString: "FirstName LastName", MaxResults: 5})
// WRONG: SecureApi.SearchClaimsExtended({Filter: "FirstName LastName"})
// WRONG: SecureApi.SearchClaimsExtended("LastNa_FirstN_{ClaimTypeAbbreviation}_1234")  // claim name pattern is NOT a search filter
```

The claim name format described in the endpoint description (e.g. `LastNa_FirstN_{ClaimTypeAbbreviation}_1234`) is an internal record identifier - do NOT use it as the Filter argument. Pass the person's display name (e.g. `"FirstName LastName"`).

## Cross-References

| Need | Use Instead |
|------|-------------|
| Already have ClaimID | `GetClaim(ClaimID)` - direct lookup, no searching |
| Search by specific field | `SearchClaimsBySystemFieldString(FieldName, Filter)` |
| Search by date range | `SearchClaimsBySystemFieldDate(FieldName, Start, End)` |
| Bulk/aggregate queries | `GetFirmAdvancedSearchesClaim` then `GetAdvancedSearchResults` |
| All open claims, reports | Advanced Searches - never use this endpoint for bulk data |