rothbard/.claude/skills/filevine-api.md

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:

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