> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Address Verification

> Verify and standardise postal addresses in GBG Go, and confirm how precisely an address matches, from the delivery point down to the administrative area.

export const ModuleToc = () => {
  const ref = useRef(null);
  const [items, setItems] = useState([]);
  const [inVariant, setInVariant] = useState(false);
  useEffect(() => {
    const toc = ref.current;
    if (!toc) return;
    const sections = [{
      label: "Capabilities",
      match: "capabilities",
      suffix: true
    }, {
      label: "Default outcomes",
      match: "default outcomes"
    }, {
      label: "Input payload",
      match: "input payload"
    }, {
      label: "Sample response",
      match: "sample response"
    }];
    const related = {
      label: "Related guides",
      match: "related guides and tutorials"
    };
    const selector = "h2[id], h3[id], h4[id], h5[id], h6[id]";
    const read = heading => ({
      heading,
      level: Number(heading.tagName.slice(1)),
      text: heading.textContent.replace(/​/g, "").trim()
    });
    const matches = (entry, section) => {
      const text = entry.text.toLowerCase();
      return text === section.match || section.suffix && text.endsWith(` ${section.match}`);
    };
    const isSection = entry => sections.some(section => matches(entry, section));
    const after = entry => toc.compareDocumentPosition(entry.heading) & Node.DOCUMENT_POSITION_FOLLOWING;
    const link = (entry, label) => ({
      label: label || entry.text,
      id: entry.heading.id
    });
    const sectionLinks = pool => sections.map(section => {
      const entry = pool.find(candidate => matches(candidate, section));
      return entry ? link(entry, section.label) : null;
    }).filter(Boolean);
    const root = toc.closest("#content-area") || document.body;
    const key = window.location.pathname;
    if (!root.moduleTocPage || root.moduleTocPage.key !== key) {
      root.moduleTocPage = {
        key,
        headings: Array.from(root.querySelectorAll(selector)).filter(heading => !heading.closest("details")).map(read)
      };
    }
    const page = root.moduleTocPage.headings.filter(after);
    const relatedEntry = page.find(entry => matches(entry, related));
    const relatedLink = relatedEntry ? [link(relatedEntry, related.label)] : [];
    const variant = toc.closest("details");
    if (variant) {
      const own = Array.from(variant.querySelectorAll(selector)).map(read).filter(after);
      const ownLinks = sectionLinks(own);
      const shared = sectionLinks(page).filter(fallback => !ownLinks.some(existing => existing.label === fallback.label));
      const order = sections.map(section => section.label);
      const merged = [...ownLinks, ...shared].sort((a, b) => order.indexOf(a.label) - order.indexOf(b.label));
      setInVariant(true);
      setItems([...merged, ...relatedLink]);
      return;
    }
    const isVariant = (entry, index) => {
      if (isSection(entry)) return false;
      for (const next of page.slice(index + 1)) {
        if (next.level <= entry.level) return false;
        if (isSection(next)) return true;
      }
      return false;
    };
    const loose = [];
    const groups = [];
    page.forEach((entry, index) => {
      if (isVariant(entry, index)) groups.push({
        entry,
        pool: []
      }); else if (isSection(entry)) (groups.length ? groups[groups.length - 1].pool : loose).push(entry);
    });
    const variants = groups.map(group => ({
      ...link(group.entry),
      children: sectionLinks(group.pool)
    })).filter(group => group.children.length);
    setInVariant(false);
    setItems(variants.length > 1 ? [...sectionLinks(loose), ...variants, ...relatedLink] : [...sectionLinks(page), ...relatedLink]);
  }, []);
  const linkClass = "block -ml-px border-l border-transparent pl-4 text-gray-600 dark:text-gray-400 hover:border-gray-400 hover:text-gray-900 dark:hover:text-gray-200";
  return <nav ref={ref} aria-label={inVariant ? "In this variant" : "On this page"} data-module-toc="" className="module-toc not-prose my-6 text-sm">
      {items.length > 0 && <p className="mb-2 font-medium text-gray-900 dark:text-gray-200">
          {inVariant ? "In this variant" : "On this page"}
        </p>}
      {items.length > 0 && <ul className="space-y-1.5 border-l border-gray-200 dark:border-white/10">
          {items.map(item => <li key={item.id}>
              <a href={`#${item.id}`} className={item.children ? `${linkClass} font-medium text-gray-800 dark:text-gray-200` : linkClass}>
                {item.label}
              </a>
              {item.children && <ul className="mt-1.5 space-y-1.5 pl-4">
                  {item.children.map(child => <li key={child.id}>
                      <a href={`#${child.id}`} className={linkClass}>
                        {child.label}
                      </a>
                    </li>)}
                </ul>}
            </li>)}
        </ul>}
    </nav>;
};

Verify and standardise postal addresses globally. Returns verification level, postal-code match status, match score, and an overall address quality level. A separate CASS-certified variant is available for US-only journeys requiring USPS Delivery Point Validation.

This page documents the **Address Verification** module, including its variants, capabilities, and the result values it returns.

<ModuleToc />

## Global

Verifies and standardises postal addresses globally. Returns verification level, postal-code match, match score, and GBG Address Quality Level. Country is supplied via the customer-configurable config form.

### Capabilities

#### Address verified

True if the service returned at least one match for the input address.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Verification level

Granularity at which the address was verified, derived from the AVC.

| Value | Description |
| - | - |
| `DELIVERY_POINT` | Verified to the individual delivery point (sub-building, e.g. apartment/suite). AVC level 5. |
| `PREMISE` | Verified to the building / premise level. AVC level 4. |
| `THOROUGHFARE` | Verified to street / thoroughfare only. AVC level 3. |
| `LOCALITY` | Verified to city / locality only. AVC level 2. |
| `ADMINISTRATIVE_AREA` | Verified to state / region only. AVC level 1. |
| `NONE` | Address could not be verified to any level. |

#### Postal code verified

True if the postal code was verified by the service.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Match score

Match score 0-100. Indicates how much correction was applied to the input (100 = no changes). Not a confidence percentage.

| Detail | Description |
| - | - |
| Type | Integer |
| Range | 0–100 |
| Default | `0` |

#### Multiple matches

True if the input address was ambiguous — the service could not resolve a single result. In the Verify mode this variant uses, ambiguity is signalled by AVC verification status 'A' (a single record); a >1 candidate count (Search mode) also sets it.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Geocoded

Reserved. True if the service returned latitude/longitude for the match. The module does not request geocoding, so this is currently always false.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Country recognised

True if the supplied country was recognised by the service (no parsing error).

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Service error

True if the address-verification service call failed or threw an exception. Distinguishes a runtime/integration failure from a legitimate Not Verified result.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Input address quality level

GBG Address Quality Level (1-4). Shared scoring scheme with GBG SIP. 1=Excellent (verified at PREMISE/DELIVERY\_POINT with postal code match), 2=Good (verified at PREMISE/DELIVERY\_POINT without postal, or any verification with postal match), 3=Poor (verified at lower levels, or ambiguous/multiple matches), 4=Not possible to validate.

| Value | Description |
| - | - |
| `1` | Excellent quality |
| `2` | Good quality |
| `3` | Poor quality |
| `4` | Not possible to validate |

### Default outcomes

The module is pre-configured with the following default outcomes, which can be used in evaluation and routing logic within the journey designer.

| Outcome | Condition | Description |
| - | - | - |
| `Error` | Service Error is `true` | The address check couldn't be completed because the service returned an error. |
| `Verified` | Address Verified is `true` and Postal Code Verified is `true` and Input Address Quality Level is `1` and (Verification Level is `DELIVERY_POINT` or Verification Level is `PREMISE`) | The full address was confirmed to the building or delivery point, and the postal code matched. This is the strongest result the module returns. |
| `Ambiguous` | Multiple Matches is `true` | The address matched more than one record, so the service couldn't resolve it to a single result. Ask your customer to confirm the address. |
| `Partially Verified` | Address Verified is `true` and (Verification Level is `DELIVERY_POINT` or Verification Level is `PREMISE` or Verification Level is `THOROUGHFARE` or Verification Level is `LOCALITY` or Verification Level is `ADMINISTRATIVE_AREA`) | The address was confirmed, but to a lower level of detail than a full match, for example, to the street or the town rather than the building. |
| `Not Verified` | Address Verified is `false` and Multiple Matches is `false` | The address matched no records, and it wasn't ambiguous. Treat it as unconfirmed. |
| `Indeterminate` | default, when no conditions matched | None of the other conditions matched, so the module couldn't classify the result. |

### Input payload

The following is a sample payload used to submit data to the **Global** module for processing.

```json JSON theme={null}
{
  "context": {
    "config": {
      "country": "GBR"
    },
    "subject": {
      "identity": {
        "currentAddress": {
          "locality": "London",
          "thoroughfare": "1 Park Road"
        }
      }
    }
  }
}
```

| Field | Required | Description |
| - | - | - |
| `CurrentAddress` | Yes | The customer’s address to verify, including the building, street, town, and postal code. |

### Sample response

The following is a sample response returned by the module.

```json JSON theme={null}
{
  "response": {
    "advice": {
      "addressVerified": false,
      "countryRecognized": true,
      "gbgAddressQualityLevel": "3",
      "geocoded": false,
      "matchScore": 100,
      "multipleMatches": true,
      "postalCodeVerified": true,
      "serviceError": false,
      "verificationLevel": "PREMISE"
    },
    "outcome": "Ambiguous"
  }
}
```

## US (CASS)

USPS CASS-certified address verification for US addresses. Returns DPV (Delivery Point Validation) status alongside the standard verification fields. Country is hard-coded to USA.

### Capabilities

#### Address verified

True if the service returned at least one match for the input address.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### DPV confirmed indicator

USPS Delivery Point Validation indicator: Y = deliverable, S = deliverable but missing secondary unit, D = building confirmed but secondary required, N = not deliverable, NOT\_FOUND = not found in USPS database or DPV not attempted (e.g. ambiguous match).

| Value | Description |
| - | - |
| `Y` | Address is fully deliverable |
| `S` | Address is deliverable but missing secondary (suite/unit) number |
| `D` | Building confirmed but secondary number required and not provided |
| `N` | Address is not deliverable |
| `NOT_FOUND` | Address not found in the USPS database, or DPV was not attempted (e.g. multiple ambiguous matches) |

#### Verification level

Granularity at which the address was verified, derived from the AVC.

| Value | Description |
| - | - |
| `DELIVERY_POINT` | Verified to the individual delivery point (sub-building). AVC level 5. |
| `PREMISE` | Verified to the building / premise level. AVC level 4. |
| `THOROUGHFARE` | Verified to street / thoroughfare only. |
| `LOCALITY` | Verified to city / locality only. |
| `ADMINISTRATIVE_AREA` | Verified to state / region only. |
| `NONE` | Address could not be verified to any level. |

#### Postal code verified

True if the ZIP code was verified by USPS.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Match score

Match score 0-100. Indicates how much correction was applied to the input (100 = no changes).

| Detail | Description |
| - | - |
| Type | Integer |
| Range | 0–100 |
| Default | `0` |

#### Multiple matches

True if the input address was ambiguous — the service could not resolve a single result. In the Verify mode this variant uses, ambiguity is signalled by AVC verification status 'A' (a single record); a >1 candidate count (Search mode) also sets it.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Geocoded

Reserved. True if the service returned latitude/longitude for the match. The module does not request geocoding, so this is currently always false.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Country recognised

True if the country was recognised (always true for CASS variant since country is hard-coded to USA).

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `true` |

#### Service error

True if the address-verification service call failed or threw an exception. Distinguishes a runtime/integration failure from a legitimate Not Verified result.

| Detail | Description |
| - | - |
| Type | Boolean |
| Default | `false` |

#### Input address quality level

GBG Address Quality Level (1-4). Shared scoring scheme with GBG SIP. For this CASS variant the level is governed by USPS DPV: 1=Excellent (DPV 'Y' and verified at PREMISE/DELIVERY\_POINT with postal match), 2=Good (DPV 'S'/'D' — USPS confirms the building is deliverable but the address is incomplete, regardless of AVC level), 3=Poor (ambiguous/multiple matches), 4=Not possible to validate (DPV 'N'/NOT\_FOUND, or no match). 'D' here is the DPV indicator, not an AVC level.

| Value | Description |
| - | - |
| `1` | Excellent quality |
| `2` | Good quality |
| `3` | Poor quality |
| `4` | Not possible to validate |

### Default outcomes

The module is pre-configured with the following default outcomes, which can be used in evaluation and routing logic within the journey designer.

| Outcome | Condition | Description |
| - | - | - |
| `Error` | Service Error is `true` | The address check couldn't be completed because the service returned an error. |
| `Verified` | DPV Confirmed Indicator is `Y` and Multiple Matches is `false` | USPS confirmed the address as deliverable, and it matched a single record. |
| `Partially Verified` | (DPV Confirmed Indicator is `S` or DPV Confirmed Indicator is `D`) and Multiple Matches is `false` | USPS confirmed the building, but the address is missing a secondary number such as a suite or unit, or one is required and wasn't provided. |
| `Ambiguous` | Multiple Matches is `true` | The address matched more than one record, so the service couldn't resolve it to a single result. Ask your customer to confirm the address. |
| `Not Verified` | (DPV Confirmed Indicator is `N` or DPV Confirmed Indicator is `NOT_FOUND`) and Multiple Matches is `false` | USPS reported the address as undeliverable, or couldn't find it in its database. |
| `Indeterminate` | default, when no conditions matched | None of the other conditions matched, so the module couldn't classify the result. |

### Input payload

The following is a sample payload used to submit data to the **US (CASS)** module for processing.

```json JSON theme={null}
{
  "context": {
    "subject": {
      "identity": {
        "currentAddress": {
          "administrativeArea": "WA",
          "locality": "Seattle",
          "thoroughfare": "100 1st Avenue"
        }
      }
    }
  }
}
```

| Field | Required | Description |
| - | - | - |
| `CurrentAddress` | Yes | The customer’s address to verify, including the building, street, town, and postal code. |

### Sample response

The following is a sample response returned by the module.

```json JSON theme={null}
{
  "response": {
    "advice": {
      "addressVerified": false,
      "countryRecognized": true,
      "dpvConfirmedIndicator": "NOT_FOUND",
      "gbgAddressQualityLevel": "3",
      "geocoded": false,
      "matchScore": 100,
      "multipleMatches": true,
      "postalCodeVerified": true,
      "serviceError": false,
      "verificationLevel": "ADMINISTRATIVE_AREA"
    },
    "outcome": "Ambiguous"
  }
}
```