# Introduction (/)

Fieldgeist is an AI lab building tools for real estate. **Verify**, its first tool, is an address model: **US-LEX-1**, a purpose-built neural model trained on real US addresses, that reads free text the way USPS Publication 28 defines an address. Behind it sits a parcel index Fieldgeist builds, so every reading can be matched to a property. The API is how you use both today.

<Cards>
  <Card title="US-LEX-1, the Verify model" href="/concepts/model">How it reads an address, its versions, and how it improves.</Card>
</Cards>

Verify does two jobs:

- **Parse.** Send one line of free text, get back the address split into USPS Publication 28 components (house number, directionals, street, suffix, unit, city, state, ZIP), the standardized delivery lines, a confidence score and warnings for anything missing or unclear. The model reads every line, at the edge, inside the request.
- **Look up.** Send a parsed address, get back the parcel it belongs to: a stable Fieldgeist ID, the county APN, the county FIPS code and coordinates. When the address could be more than one parcel, or needs a unit number to pick one, the answer says so instead of guessing.

```bash
curl https://api.fieldgeist.com/v1/verify/parse \
  -H "Authorization: Bearer $FIELDGEIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"line": "350 5th ave apt 21b new york ny 10118"}'
```

```json
{
  "input": "350 5th ave apt 21b new york ny 10118",
  "type": "street",
  "components": {
    "city": "NEW YORK",
    "addressNumber": "350",
    "streetSuffix": "AVE",
    "streetName": "5TH",
    "occupancyType": "APT",
    "occupancyId": "21B",
    "state": "NY",
    "zip5": "10118"
  },
  "lines": ["350 5TH AVE APT 21B", "NEW YORK NY  10118"],
  "warnings": [],
  "confidence": 0.9999020747368791,
  "model": { "name": "us-lex-1", "version": "0.1.0", "backend": "model" }
}
```

## Who it's for [#who-its-for]

- **Proptech teams** that need clean addresses and a reliable link from an address to a property record.
- **AI agent builders** whose agents call address and property tools and need typed answers with explicit uncertainty (`ambiguous`, `unit_required`) rather than a confident guess.

## What it covers [#what-it-covers]

| | Parse | Look up | Look up by ID |
| --- | --- | --- | --- |
| Endpoint | `POST /v1/verify/parse` | `POST /v1/verify/lookup` | `GET /v1/verify/lookup/{fieldgeist_id}` |
| Input | One line of text | Address components (or a parse response) | A Fieldgeist ID (`adr_…`) |
| Output | Components, delivery lines, confidence, warnings | Match status, parcel IDs, APN, FIPS, coordinates, candidates | One parcel and its address |
| Scope | US addresses: street, PO box, rural route, military, general delivery | Street addresses | Any ID a lookup returned |

The parser standardizes what you send; it does not correct spelling. Near-miss street names are handled by the lookup, which flags them with `fuzzy: true` and a lower confidence.

## Start here [#start-here]

<Cards>
  <Card title="Quickstart" href="/quickstart">Create a key and parse your first address.</Card>
  <Card title="Authentication" href="/authentication">API keys, the Authorization header and key hygiene.</Card>
  <Card title="Look up a parcel" href="/api-reference/lookup">Statuses, candidates and units.</Card>
  <Card title="Credits and billing" href="/billing">Prepaid credits, billed per answer.</Card>
</Cards>