# Filevine API Curl Skill

This skill enables intelligent exploration of the Filevine API by making curl requests and analyzing data patterns.

## Capabilities

1. **Discover relevant data within a project** - Search across all endpoints used in sync.py
2. **Make educated guesses** - Use patterns from sample data to infer where data might exist
3. **Query specific fields** - Search for fields like "matter number", "case number", dates, etc.

## API Endpoints Discovered

Based on analysis of `sync.py`, the following endpoints are used:

| Endpoint | Purpose | Related Code |
|----------|---------|--------------|
| `Projects/{id}` | Project details (name, URLs, dates, phase) | `fetch_project_detail()` |
| `Projects/{id}/team` | Team members and roles | `fetch_project_team()` |
| `Projects/{id}/tasks` | Project tasks | `fetch_project_tasks()` |
| `Projects/{id}/Forms/{form}` | Specific forms (datesAndDeadlines, newFileReview, etc.) | `fetch_form()` |
| `Projects/{id}/Contacts` | Project contacts | `fetch_contacts()` |
| `Contacts/{id}` | Client information | `fetch_client()` |
| `Projects/{id}/Collections/{collection}` | Collections (serviceInfo) | `fetch_collection()` |

## Sample Data Patterns

From examining `examples/*.json`, here are common patterns:

**Project-level fields (Projects/{id}):**
- `projectName` - Full project name
- `number` - Project number
- `incidentDate` - Incident date
- `projectEmailAddress` - Email address
- `projectUrl` - Link to Filevine
- `phaseName` - Current phase
- `createdDate` - Creation date

**DatesAndDeadlines form:**
- `caseNumber` - Case number
- `dateCaseFiled` - Case filed date
- `defaultDate` - Default date
- `trialDate` - Trial date
- `mSCDate` - MSC date
- `noticeExpirationDate` - Notice expiration
- `judgmentDate` - Judgment date

**NewFileReview form:**
- `noticeServiceDate` - When notice was served
- `noticeExpirationDate` - Notice expiration
- `noticeType` - Type of notice (NP, PPQ, etc.)
- `amountDemandedInNotice` - Amount demanded

**ComplaintInfo form:**
- `totalDamagesSought` - Total damages
- `complaintVerificationBy` - Verification method

## Usage

When the user asks about finding data, follow this workflow:

### 1. Parse the Query

Identify what the user wants to find:
- Field name (e.g., "matter number", "case number", "trial date")
- Context (e.g., "in a project", "in the datesAndDeadlines form")

### 2. Generate Endpoint Candidates

Based on the query, suggest multiple endpoints to check:

**For case/project identifiers:**
- `Projects/{id}` (check `number`, `caseNumber` fields)
- `Projects/{id}/Forms/datesAndDeadlines` (check `caseNumber` field)
- `Projects/{id}/Forms/matterOverview` (check `matterNumber` field)

**For dates:**
- `Projects/{id}` (check `incidentDate`, `createdDate`)
- `Projects/{id}/Forms/datesAndDeadlines` (check `trialDate`, `mSCDate`, `defaultDate`, etc.)
- `Projects/{id}/Forms/newFileReview` (check `noticeServiceDate`)

**For contact/defendant info:**
- `Projects/{id}/Contacts` (check contact list for defendant)
- `Contacts/{client_id}` (check full contact info)

**For attorney/team:**
- `Projects/{id}/team` (check `teamOrgRoles` for "Assigned Attorney", "Primary", etc.)

**For notices:**
- `Projects/{id}/Forms/newFileReview` (check `noticeType`, `noticeExpirationDate`, etc.)
- `Projects/{id}/Collections/serviceInfo` (check service dates)

### 3. Execute curl Commands

For each candidate endpoint, construct and execute curl commands using the auth headers from the codebase:

```bash
curl -X GET "https://api.filevineapp.com/fv-app/v2/Projects/{PROJECT_ID}/{ENDPOINT}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {BEARER_TOKEN}" \
  -H "x-fv-orgid: {ORG_ID}" \
  -H "x-fv-userid: {USER_ID}"
```

Use the project ID from sample data (e.g., `15974631` or `15914808`) as a placeholder.

### 4. Analyze Results

Look for the queried field in the JSON response:
- Search field names (not values)
- Check nested objects and arrays
- Note which endpoints actually contain the data

### 5. Report Findings

Provide:
1. The field value(s) found
2. The endpoint(s) that contain it
3. Any related fields discovered in the same endpoint
4. Context about how this data is used in the application

## Common Patterns to Guess From

When the user asks "What endpoint should I hit to find [field]?", consider:

**Field Mapping:**
| Common Field Names | Likely Endpoints |
|-------------------|------------------|
| `matterNumber`, `matter number` | `Projects/{id}/Forms/matterOverview` |
| `caseNumber`, `case number` | `Projects/{id}/Forms/datesAndDeadlines` |
| `incident date`, `incidentDate` | `Projects/{id}`, `Projects/{id}/Forms/datesAndDeadlines` |
| `trial date`, `trialDate` | `Projects/{id}/Forms/datesAndDeadlines` |
| `notice service date`, `noticeServiceDate` | `Projects/{id}/Forms/newFileReview` |
| `notice expiration date`, `noticeExpirationDate` | `Projects/{id}/Forms/newFileReview` |
| `notice type` | `Projects/{id}/Forms/newFileReview` |
| `assigned attorney` | `Projects/{id}/team` (role: "Assigned Attorney") |
| `primary contact`, `staff person` | `Projects/{id}/team` (role: "Primary") |
| `defendant` | `Projects/{id}/Contacts` (filter for "Defendant" role) |
| `client` | `Contacts/{client_id}` or `Projects/{id}` (clientId field) |

## Environment Setup

When executing curl commands, use these placeholder values (user should provide actual values):

- `PROJECT_ID` - Use sample IDs like 15974631 or 15914808
- `ORG_ID` - From FILEVINE_ORG_ID env var
- `USER_ID` - From FILEVINE_USER_ID env var
- `BEARER_TOKEN` - From FilevineClient.get_bearer_token()

## Tips

1. Start with the most likely endpoints first
2. The sample data shows that many fields are duplicated across endpoints - check multiple places
3. Date fields are often in ISO format in API responses
4. Some forms (like `newFileReview`) contain multiple related date fields
5. Team roles use specific names - "Assigned Attorney", "Primary", "Secondary Paralegal"
6. Contact objects in arrays may have `personTypes` to identify their role

## Example Workflow

User: "What endpoint should I hit to find the matter number?"

1. Identify: User wants "matter number" field
2. Guess: Matter number might be in `Projects/{id}/Forms/matterOverview` based on sample data patterns
3. Check: `Projects/{id}` also has `number` field
4. Execute: curl to both endpoints with project 15974631
5. Report: Found `number` in project root and `matterNumber` in matterOverview form