Address Verification

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. This page documents the Address Verification module, including its variants, capabilities, and the result values it returns.

Address Verification: Global

Capabilities

The module returns the following 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.

Code	Label	Description
`DELIVERY_POINT`	Delivery Point	Verified to the individual delivery point (sub-building, e.g. apartment/suite). AVC level 5.
`PREMISE`	Premise	Verified to the building / premise level. AVC level 4.
`THOROUGHFARE`	Thoroughfare	Verified to street / thoroughfare only. AVC level 3.
`LOCALITY`	Locality	Verified to city / locality only. AVC level 2.
`ADMINISTRATIVE_AREA`	Administrative Area	Verified to state / region only. AVC level 1.
`NONE`	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 for future use. This capability indicates whether the service returned a latitude and longitude for the matched address. The module doesn’t currently request geocoding, so the value is 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.

Code	Label	Description
`1`	1	Excellent quality
`2`	2	Good quality
`3`	3	Poor quality
`4`	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 isTrue	The address check couldn’t be completed because the service returned an error.
`Verified`	Address Verified isTrue and Postal Code Verified isTrue 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 isTrue	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 isTrue 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 isFalse and Multiple Matches isFalse	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

{
  "context": {
    "subject": {
      "identity": {
        "currentAddress": {
          "thoroughfare": "1 Park Road",
          "locality": "London"
        }
      }
    },
    "config": {
      "country": "GBR"
    }
  }
}

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

{
  "response": {
    "advice": {
      "addressVerified": false,
      "verificationLevel": "PREMISE",
      "postalCodeVerified": true,
      "matchScore": 100,
      "multipleMatches": true,
      "geocoded": false,
      "countryRecognized": true,
      "gbgAddressQualityLevel": "3",
      "serviceError": false
    },
    "outcome": "Ambiguous"
  }
}

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

The module returns the following 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).

Code	Label	Description
`Y`	Y - Confirmed	Address is fully deliverable
`S`	S - Confirmed, missing secondary	Address is deliverable but missing secondary (suite/unit) number
`D`	D - Confirmed, secondary required	Building confirmed but secondary number required and not provided
`N`	N - Not deliverable	Address is not deliverable
`NOT_FOUND`	NOT_FOUND - Not found / not checked	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.

Code	Label	Description
`DELIVERY_POINT`	Delivery Point	Verified to the individual delivery point (sub-building). AVC level 5.
`PREMISE`	Premise	Verified to the building / premise level. AVC level 4.
`THOROUGHFARE`	Thoroughfare	Verified to street / thoroughfare only.
`LOCALITY`	Locality	Verified to city / locality only.
`ADMINISTRATIVE_AREA`	Administrative Area	Verified to state / region only.
`NONE`	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

Detail	Description
Type	Boolean
Default	`false`

Geocoded

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.

Code	Label	Description
`1`	1	Excellent quality
`2`	2	Good quality
`3`	3	Poor quality
`4`	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 isTrue	The address check couldn’t be completed because the service returned an error.
`Verified`	DPV Confirmed Indicator is `Y` and Multiple Matches isFalse	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 isFalse	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 isTrue	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 isFalse	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

{
  "context": {
    "subject": {
      "identity": {
        "currentAddress": {
          "thoroughfare": "100 1st Avenue",
          "locality": "Seattle",
          "administrativeArea": "WA"
        }
      }
    }
  }
}

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

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

Get Started

Platform

Developer Integration

Digital IDs

Resources

Address Verification: Global

Capabilities

Address verified

Verification level

Postal code verified

Match score

Multiple matches

Geocoded

Country recognised

Service error

Input address quality level

Default outcomes

Input payload

Sample response

Address Verification: US (CASS)

Capabilities

Address verified

DPV confirmed indicator

Verification level

Postal code verified

Match score

Multiple matches

Geocoded

Country recognised

Service error

Input address quality level

Default outcomes

Input payload

Sample response

​Address Verification: Global

​Capabilities

​Address verified

​Verification level

​Postal code verified

​Match score

​Multiple matches

​Geocoded

​Country recognised

​Service error

​Input address quality level

​Default outcomes

​Input payload

​Sample response

​Address Verification: US (CASS)

​Capabilities

​Address verified

​DPV confirmed indicator

​Verification level

​Postal code verified

​Match score

​Multiple matches

​Geocoded

​Country recognised

​Service error

​Input address quality level

​Default outcomes

​Input payload

​Sample response

Address Verification: Global

Capabilities

Address verified

Verification level

Postal code verified

Match score

Multiple matches

Geocoded

Country recognised

Service error

Input address quality level

Default outcomes

Input payload

Sample response

Address Verification: US (CASS)

Capabilities

Address verified

DPV confirmed indicator

Verification level

Postal code verified

Match score

Multiple matches

Geocoded

Country recognised

Service error

Input address quality level

Default outcomes

Input payload

Sample response