---
title: "Quickstart"
url: "https://lookvalid.com/docs/quickstart.md"
canonical_url: "https://lookvalid.com/docs/quickstart"
last_updated: "2026-10-22"
type: "how-to"
summary: "Get an API key and make your first LookValid request in cURL, Node.js or Python."
related: ["https://lookvalid.com/docs.md", "https://lookvalid.com/docs/authentication.md"]
---

# Quickstart

Get an API key and make your first LookValid request in cURL, Node.js or Python.

Make your first lookup in a few minutes. You need an account, an API key and credits in your balance. Credits come with a plan: Starter, Growth and Professional each start with a 7-day trial for $1 that allows 100 credits, and Enterprise is set up on a call.

## 1. Get an API key

1. Email [hello@lookvalid.com](mailto:hello@lookvalid.com?subject=Get%20started%3A%20API%20key) with the lookups you need and roughly how many a month.
2. We set up your account and a plan with 100 credits to try any lookup.
3. We send your API key. Copy it right away. It is shown once and cannot be recovered later. If you lose it, ask us to revoke it and send another.

Keys start with `lv_live_`. Keep the key in an environment variable, never in source control or in browser code:

```sh
export LOOKVALID_API_KEY="lv_live_..."
```

## 2. Make your first request

Every lookup is a `POST` to `https://YOUR_API_HOST/v1/<product>` with a JSON body. This example looks up an IP address with the [IP Intelligence](https://lookvalid.com/docs/api/ip.md) product.

**cURL**

```sh
curl -X POST https://YOUR_API_HOST/v1/ip \
  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.7"}'
```

**Node.js**

```js
const response = await fetch("https://YOUR_API_HOST/v1/ip", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ip": "203.0.113.7"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
console.log(result.found, result.data, result.credits_charged);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://YOUR_API_HOST/v1/ip",
    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
    json={
        "ip": "203.0.113.7",
    },
    timeout=30,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}")
print(result["found"], result["data"], result["credits_charged"])
```

The request body for every product is described on its [reference page](https://lookvalid.com/docs/api.md).

## 3. Read the response

A lookup that ran returns HTTP 200 whether or not it found something:

```json
{
  "request_id": "req_...",
  "product": "ip",
  "found": true,
  "data": { "...": "the result" },
  "reason": null,
  "sources": ["where the data came from"],
  "credits_charged": 1,
  "credits_remaining": 99,
  "cache_hit": false,
  "cache": { "hit": false, "cached_at": "...", "expires_at": "..." }
}
```

- `found` tells you whether data came back. `found: false` is a normal answer, and `reason` says why.
- `data` holds the result, or `null` when nothing was found.
- `sources` lists where the data came from. Show any attribution listed there wherever you show the result.
- `credits_charged` and `credits_remaining` show what this request cost and what is left. The same numbers arrive in the `X-Credits-Charged` and `X-Credits-Remaining` headers.
- `cache_hit` is true when you already paid for this lookup in the last 7 days. A repeat costs nothing.

This block shows the shape of a response, not the result of a real lookup. Each reference page lists every field of `data` for its product.

## 4. Check your balance

`GET /v1/account` returns your balance and key summary and never costs credits.

```sh
curl https://YOUR_API_HOST/v1/account \
  -H "Authorization: Bearer $LOOKVALID_API_KEY"
```

## 5. Handle errors

Errors use one JSON envelope with a stable `code`, a `fix` that says what to do, and a `retryable` flag. Nothing is charged for an error. Branch on `code`, never on the message text. See [errors](https://lookvalid.com/docs/errors.md).

## Next steps

- [Credits and billing](https://lookvalid.com/docs/credits-and-billing.md) explains exactly when you are charged.
- [Rate limits](https://lookvalid.com/docs/rate-limits.md) shows how to stay under the limit and what to do on a 429.
- [MCP server](https://lookvalid.com/docs/mcp.md) puts every lookup in your AI assistant.

## Related

- [Documentation](https://lookvalid.com/docs.md)
- [Authentication](https://lookvalid.com/docs/authentication.md)