---
title: "Node.js"
description: "Official CarsXE SDK for Node.js and TypeScript."
canonical_url: "https://docs.carsxe.com/docs/sdks/node"
markdown_url: "https://docs.carsxe.com/docs/sdks/node.md"
last_updated: "1980-01-01"
---

# Node.js
URL: /docs/sdks/node
LLM index: /llms.txt
Description: Official CarsXE SDK for Node.js and TypeScript.

The `@carsxe/sdk` package is the official CarsXE client for Node.js and TypeScript. It wraps the REST API with typed methods, handles authentication, and throws structured errors. Requires Node.js 18 or later.

## Installation

```bash
npm install @carsxe/sdk
# yarn add @carsxe/sdk
# pnpm add @carsxe/sdk
# bun add @carsxe/sdk
```

## Quick start

<CodeGroup title="Decode a VIN">

```ts
import { CarsXE } from '@carsxe/sdk'

const carsxe = new CarsXE({ apiKey: process.env.CARSXE_API_KEY! })

const result = await carsxe.decodeVin('WBAFR7C57CC811956')
console.log(result.data.make, result.data.model, result.data.year)
```

</CodeGroup>

## Methods

### Core

| Method | Description |
|---|---|
| `decodeVin(vin)` | Decode a 17-character VIN into full vehicle specifications |
| `getMarketValue(params)` | Retail, trade-in, and auction value estimates |
| `getRecalls(params)` | Open safety recalls by VIN, make, model, or year |
| `decodePlate(params)` | VIN lookup from a license plate (50+ countries) |
| `getVehicleHistory(vin)` | Title events, salvage, junk, and insurance records |

### Bulk recall batch

| Method | Description |
|---|---|
| `submitBulkRecallBatch(params)` | Submit a batch of VINs for recall lookup |
| `getBulkRecallBatchStatus(batchId)` | Poll job status |
| `getBulkRecallBatchResults(batchId)` | Retrieve completed results |
| `getBulkRecallBatchDownloadUrl(batchId)` | Get a CSV download URL |

## Error handling

All methods throw on non-2xx responses. Wrap calls in `try/catch`:

```ts
import { CarsXE } from '@carsxe/sdk'

const carsxe = new CarsXE({ apiKey: process.env.CARSXE_API_KEY! })

try {
  const result = await carsxe.decodeVin('WBAFR7C57CC811956')
  console.log(result.data)
} catch (err) {
  // err.statusCode, err.code, err.message
  console.error('CarsXE error:', err)
}
```

## Best practices

**Create one instance and reuse it.** The client reuses the underlying `fetch` connection pool — instantiating per-request wastes resources.

```ts
// lib/carsxe.ts
import { CarsXE } from '@carsxe/sdk'

export const carsxe = new CarsXE({ apiKey: process.env.CARSXE_API_KEY! })
```

**Store your key in an environment variable.** Never hardcode it or commit it to source control.

```bash
# .env
CARSXE_API_KEY=your_key_here
```

**TypeScript types are included.** The package ships full `.d.ts` declarations — no `@types` package needed. All response shapes (`VehicleSpec`, `MarketValue`, `Recall`, etc.) are exported directly from `@carsxe/sdk`.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).