Skip to main content

​
Overview

The Parse Goal endpoint uses AI to extract structured parameters from natural language financial goal descriptions. It intelligently parses the goal type, target amount, timeline, and any constraints mentioned by the user.

​
Endpoint

POST /llm/parse-goal

​
Request Body

​
goal
string
required
Natural language description of the financial goal. Examples:
  • “Save $50k for a house down payment in 3 years”
  • “Retire comfortably in 30 years”
  • “Build a $15,000 emergency fund”
  • “Pay off my debt within 5 years”

​
Response

​
goalType
string
The categorized goal type. One of:
  • retirement - retiring, stop working, financial independence
  • major_purchase - house, car, boat, etc.
  • emergency_fund - rainy day fund, safety net, 6 months expenses
  • debt_payoff - pay off loans, become debt free
  • travel - vacation, trip, sabbatical
  • education - college, degree, certification
  • investment - grow wealth, portfolio target
  • custom - anything else
​
targetAmount
number | null
Target amount in USD. Returns null if amount cannot be determined from the goal description.For vague descriptions, the AI estimates reasonable defaults:
  • “comfortable retirement” → $1,000,000
  • “house down payment” → $60,000
  • “emergency fund” → $15,000
​
timelineMonths
number | null
Timeline in months. Returns null if timeline cannot be determined.For vague timelines, the AI estimates:
  • “in a few years” → 36 months
  • “by retirement” → 420 months (35 years)
  • “soon” → 12 months
  • “long term” → 120 months (10 years)
​
constraints
string[]
Array of any constraints or conditions mentioned in the goal description. Empty array if none mentioned.
​
needsClarification
boolean
Indicates whether the goal description is ambiguous and requires clarification from the user.Set to true when:
  • Target amount is unrealistically low for the goal type
  • Timeline is missing for a time-sensitive goal
  • Goal description is too vague to estimate amounts
​
clarifyingQuestions
string[] | null
Array of questions to ask the user for clarification. Only present when needsClarification is true.Examples:
  • “A corvette typically costs 50,000−50,000-100,000. Did you mean 50,000or50,000 or 100,000?”
  • “When would you like to buy this car?”

​
Examples

​
Clear Goal with All Parameters

curl -X POST https://api.drift.example/llm/parse-goal \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Save $50k for a house down payment in 3 years"
  }'

​
Vague Goal Requiring Clarification

curl -X POST https://api.drift.example/llm/parse-goal \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Buy a corvette for $3"
  }'

​
Retirement Goal with Vague Timeline

curl -X POST https://api.drift.example/llm/parse-goal \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Retire comfortably"
  }'

​
Emergency Fund Goal

curl -X POST https://api.drift.example/llm/parse-goal \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Build an emergency fund to cover 6 months of expenses"
  }'

​
Travel Goal

curl -X POST https://api.drift.example/llm/parse-goal \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Take a $5,000 vacation to Europe next year"
  }'

​
Error Responses

​
error
string
Error message describing what went wrong.

​
Missing Goal Parameter

400 Bad Request
{
  "error": "Goal is required"
}

​
Server Error

500 Internal Server Error
{
  "error": "Failed to parse goal"
}

​
Implementation Notes

  • The endpoint uses Google’s Gemini 2.0 Flash model for parsing
  • If the Gemini API is unavailable, it falls back to rule-based parsing
  • The AI considers realistic cost ranges for different goal types
  • Clarification is requested when amounts seem unrealistic (e.g., $3 for a car)
  • The parser handles various formats: “$50k”, “50000”, “50,000”
  • Timeline can be specified in years or months

Build docs developers (and LLMs) love

Get started for freeTalk to us