# Overview (/verify)

**Fieldgeist Verify** is a service for US address parsing and parcel verification. It parses free text with [US-LEX-1](/models/us-lex-1), Fieldgeist's address model, and verifies the address against a parcel index Fieldgeist builds from public property records.

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. [US-LEX-1](/models/us-lex-1) 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" }
}
```

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

| | Parse | Look up | Look up by ID |
| --- | --- | --- | --- |
| Endpoint | [`POST /v1/verify/parse`](/api-reference/verify/parse) | [`POST /v1/verify/lookup`](/api-reference/verify/lookup) | [`GET /v1/verify/lookup/{fieldgeist_id}`](/api-reference/verify/lookup-by-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.

## Next [#next]

<Cards>
  <Card title="From free text to a parcel" href="/verify/parse-then-match">Parse, check, look up and handle every status.</Card>
  <Card title="Condos and units" href="/verify/condos-and-units">Buildings, unit parcels and `unit_required`.</Card>
  <Card title="Confidence and warnings" href="/verify/confidence-and-warnings">How sure an answer is, and what it couldn't settle.</Card>
  <Card title="API reference" href="/api-reference/verify/parse">Parse, Look up and Look up by ID.</Card>
</Cards>