Residual by VIN · ALG Residual API

Input

Pass parameters in the request query string.

URL Parameter	Default	Required	Description
`vin`	—	✓	A full or partial vehicle identification number.
`dataSetId`	`1`	Data set ID is optional	Selects the US data set. May be omitted to use data set 1.
`term`	`36`	Term is optional	The residual term in months.
`effectiveDate`	`2026-11-01`	Effective date is optional	The ALG edition used for the residual calculation.
`condition`	`AVERAGE`	Condition is optional	The vehicle condition. Other supported values are `ROUGH` and `CLEAN`.
`annualMileage`	15000	Annual mileage is optional	The expected distance driven per year.
`initialMileage`	Calculated	Initial mileage is optional	Defaults to zero when the model year is the effective-date year or newer; otherwise calculated from April 1 of the model year through the effective date using standard annual mileage.

Examples

curl 'https://api.alg.com/product/residual/byVin?vin=1FTEW1C51JFC30680' \
  -H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://api.alg.com/product/residual/byVin?vin=1FTEW1C51JFC30680&term=48' \
  -H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://api.alg.com/product/residual/byVin?vin=1FTEW1C51JFC30680&term=60&condition=CLEAN&annualMileage=12000&initialMileage=500' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Output

The response includes the resolved vehicle and every value applied to the residual calculation, including defaults.

Property	Type	Description
`vin`	String	The full or partial VIN used to resolve the vehicle.
`dataSetId`	Integer	The data set used for the residual calculation.
`modelYear`	Integer	The resolved vehicle model year.
`make`	String	The resolved vehicle make.
`model`	String	The resolved vehicle model.
`trim`	String	The resolved vehicle trim.
`term`	Integer	The term in months that was applied. Returns `36` when omitted from the input.
`effectiveDate`	Date	The ALG edition that was applied. Returns the resolved most-recent date when omitted.
`condition`	String	The condition that was applied. Returns `AVERAGE` when omitted.
`annualMileage`	Integer	The annual mileage that was applied, whether supplied or defaulted.
`initialMileage`	Integer	The initial mileage that was applied, whether supplied or calculated.
`mileageUnit`	String	The mileage unit applied to mileage values: `MI` or `KM`.
`value`	Integer	The residual value in the market currency: USD for `dataSetId` 1, CAD for 2. Rounded to the nearest 25 on whole-year terms and the nearest 5 otherwise. Omitted when no residual is published for the resolved style and term.
`valuePercent`	Integer	The residual as a percentage of MSRP, rounded to a whole percentage point. For example, `15` means 15%. Omitted alongside `value` when no residual is published.

Examples

curl 'https://api.alg.com/product/residual/byVin?vin=1FTEW1C51JFC30680' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "vin": "1FTEW1C51JFC30680",
  "modelYear": 2018,
  "make": "FORD TRUCKS",
  "model": "F-150 2WD",
  "trim": "SuperCrew XLT",
  "dataSetId": 1,
  "term": 36,
  "effectiveDate": "2026-11-01",
  "condition": "AVERAGE",
  "annualMileage": 15000,
  "initialMileage": 128750,
  "mileageUnit": "MI",
  "value": 7175,
  "valuePercent": 15
}

curl 'https://api.alg.com/product/residual/byVin?vin=1FTEW1C51JFC30680&term=48' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "vin": "1FTEW1C51JFC30680",
  "modelYear": 2018,
  "make": "FORD TRUCKS",
  "model": "F-150 2WD",
  "trim": "SuperCrew XLT",
  "dataSetId": 1,
  "term": 48,
  "effectiveDate": "2026-11-01",
  "condition": "AVERAGE",
  "annualMileage": 15000,
  "initialMileage": 128750,
  "mileageUnit": "MI",
  "value": 5800,
  "valuePercent": 12
}

curl 'https://api.alg.com/product/residual/byVin?vin=1FTEW1C51JFC30680&term=60&condition=CLEAN&annualMileage=12000&initialMileage=500' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "vin": "1FTEW1C51JFC30680",
  "modelYear": 2018,
  "make": "FORD TRUCKS",
  "model": "F-150 2WD",
  "trim": "SuperCrew XLT",
  "dataSetId": 1,
  "term": 60,
  "effectiveDate": "2026-11-01",
  "condition": "CLEAN",
  "annualMileage": 12000,
  "initialMileage": 500,
  "mileageUnit": "MI",
  "value": 15975,
  "valuePercent": 34
}

Authentication

Every request must be authenticated with an API key issued to you by ALG, sent as a bearer token.

Header	Value	Description
`Authorization`	`Bearer YOUR_API_KEY`	An API key issued to you by ALG. Tied to your company. Keep it server-side.

Examples

curl 'https://api.alg.com/product/residual/byVin?vin=1FTEW1C51JFC30680' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl 'https://api.alg.com/product/residual/byVin?vin=1FTEW1C51JFC30680'
{
  "errors": [
    {
      "status": 401,
      "code": null,
      "message": "Please provide a Bearer token in the Authorization header"
    }
  ]
}