Quickstart

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 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:

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 product.

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"}'

1const response = await fetch("https://YOUR_API_HOST/v1/ip", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    "ip": "203.0.113.7"
9  }),
10});
11​
12const result = await response.json();
13if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
14console.log(result.found, result.data, result.credits_charged);

1import os
2import requests
3​
4response = requests.post(
5    "https://YOUR_API_HOST/v1/ip",
6    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
7    json={
8        "ip": "203.0.113.7",
9    },
10    timeout=30,
11)
12result = response.json()
13if not response.ok:
14    raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}")
15print(result["found"], result["data"], result["credits_charged"])

The request body for every product is described on its reference page.

3. Read the response

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

1{
2  "request_id": "req_...",
3  "product": "ip",
4  "found": true,
5  "data": { "...": "the result" },
6  "reason": null,
7  "sources": ["where the data came from"],
8  "credits_charged": 1,
9  "credits_remaining": 99,
10  "cache_hit": false,
11  "cache": { "hit": false, "cached_at": "...", "expires_at": "..." }
12}

• 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.

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.

Next steps

• Credits and billing explains exactly when you are charged.
• Rate limits shows how to stay under the limit and what to do on a 429.
• MCP server puts every lookup in your AI assistant.