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

# Oracle Integration Cloud Usage Guide

> Use the GBG Loqate Reach and GBG Loqate Verify adapters inside an Oracle Integration flow: add the Verify address action, map the request, and branch or handle errors on the response.

This guide covers using the GBG Loqate Reach and GBG Loqate Verify adapters inside an Oracle Integration flow: adding the action, mapping data into it, and working with what comes back.

If you have not installed an adapter and created a connection yet, start with the [Integration Guide](https://docs.loqate.com/integrations/oracle-integration-cloud-overview.md).

## Adding the Verify address action

Both adapters expose a single action, **Verify address**, and both are invoke only. You call them from inside a flow. Neither adapter can start an integration.

**1. Open an integration**

Open or create an integration. Any style works, including app driven, scheduled, and event driven.

**2. Add the connection**

Drag your Loqate connection onto the flow at the point where you want the address verified.

**3. Name the endpoint**

Give the endpoint a name and click **Continue**.

**4. Select the action**

Select the **Verify address** action and click **Continue**, then **Finish**.

**5. Map the request**

Open the mapper for the new invoke and map your source fields onto the [request](#request).

## Request

Both adapters accept the same two fields.

| Field | Type | Required | Notes |
| - | - | - | - |
| `address` | String | Yes | The address to verify. A single line containing the whole address is acceptable, and is usually the easiest thing to map |
| `country` | String | Yes | ISO 3166-1 alpha-2 country code, for example `GB`, `US`, `MY`. Map it on every call, see the warning below |

> [!WARNING]
>
> Always map `country`. Neither adapter works it out from the address. Leave it unmapped and GBG Loqate Reach raises a **Verification service error (502)** fault, while GBG Loqate Verify returns a normal response with an empty verified address, no AVC and no match quality. The Verify case raises no fault, so it is easy to mistake for success.

You do not need to split the address into components before calling. Loqate parses the input itself, so mapping a concatenated address line, or a single free text field captured from a form, works well.

```json theme={null}
{
  "address": "1600 Amphitheatre Parkway, Mountain View, CA 94043",
  "country": "US"
}
```

## Response: GBG Loqate Reach

| Field | Type | Description |
| - | - | - |
| `verified_address` | String | The cleaned, standardised address as a single line |
| `confidence` | Number | Confidence score from 0.0 to 1.0 |
| `recommendation` | String | The policy-aware decision to branch on: `accept`, `review`, or `reject` |
| `match_level` | String | How precisely the address matched. One of `premise`, `delivery_point`, `thoroughfare`, `locality`, `admin_area`, `country`, `none` |
| `avc` | String | The full Loqate [Address Verification Code](#reading-the-avc) |
| `fields` | Object | Standardised [address components](#address-components) |

```json theme={null}
{
  "verified_address": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351",
  "confidence": 0.97,
  "recommendation": "accept",
  "match_level": "premise",
  "avc": "V44-I44-P7-100",
  "fields": {
    "address1": "1600 Amphitheatre Pkwy",
    "locality": "Mountain View",
    "administrative_area": "CA",
    "postal_code": "94043-1351",
    "premise": "1600",
    "thoroughfare": "Amphitheatre Pkwy",
    "country": "US",
    "country_name": "United States"
  }
}
```

## Response: GBG Loqate Verify

| Field | Type | Description |
| - | - | - |
| `verified_address` | String | The cleaned, standardised address as a single line |
| `avc` | String | The full Loqate [Address Verification Code](#reading-the-avc) |
| `match_quality` | String | The Loqate [Address Quality Index](https://docs.loqate.com/report-codes/address-quality-index.md) |
| `fields` | Object | Standardised [address components](#address-components) |

Verify does not return `confidence`, `recommendation`, or `match_level`. If your flow needs a decision rather than raw codes, use the Reach adapter instead, or derive your own rules from the AVC.

## Address components

Both adapters return the same `fields` object. Loqate fills in components that were missing from the input when the reference data supplies them, so expect fields you did not send. In the example above, the request had no `country_name` or ZIP+4, but the response has both. A component is returned empty only when it does not apply to that country or the reference data cannot supply it.

| Field | Description |
| - | - |
| `address1` | First address line |
| `address2` | Second address line |
| `premise` | House or building number |
| `thoroughfare` | Street name |
| `locality` | City or town |
| `sub_administrative_area` | County or sub region |
| `administrative_area` | State or province |
| `postal_code` | Postal or ZIP code |
| `country` | ISO 3166-1 alpha-2 country code |
| `country_name` | Full country name |

Neither adapter returns geographic coordinates. If you need latitude and longitude, use the Loqate geocoding services directly. See [Address Verify](https://docs.loqate.com/our-services/address-verify/overview.md).

## Reading the AVC

Every verification returns an Address Verification Code, which is far more informative than a simple pass or fail. The leading letter is the verification status.

| Status | Meaning |
| - | - |
| `V` | Verified. A complete match against a single reference record |
| `P` | Partially verified. A partial match against a single reference record |
| `A` | Ambiguous. More than one close reference match was found |
| `R` | Reverted. Could not be verified to the minimum acceptable level |
| `U` | Unverified. Unable to verify |

In `V44-I44-P7-100`:

* `V` is the verification status (Verified).
* `44` are the post-processed and pre-processed match levels, from `0` for none up to `5` for delivery point. `4` is premise.
* `I44` is the parsing status, followed by the lexicon and context identification match levels.
* `P7` is the postcode status. `P7` means the primary postal code was verified and the secondary postal code was added or changed. Here, Loqate verified `94043` and added the ZIP+4 suffix `1351`.
* `100` is the matchscore, from 0 to 100, indicating how much the input had to change. `100` means no changes were needed.

The full breakdown is in the [Address Verification Code reference](https://docs.loqate.com/report-codes/address-verification-code.md).

## Branching on the recommendation

The most common pattern with the Reach adapter is a switch immediately after the invoke, routing on `recommendation`.

| Recommendation | Suggested handling |
| - | - |
| `accept` | Write the verified address back to your system and continue |
| `review` | Route to a manual review queue, or present the corrected address to the user for confirmation |
| `reject` | Stop and ask for re-entry, or record the failure and continue depending on how critical the address is |

Because the thresholds behind these values come from the policy set on the connection, you can make a flow stricter or more forgiving without touching the integration itself. If you need two different levels of strictness in the same instance, create two connections with different policies and use whichever the flow requires.

> [!TIP]
>
> Write `verified_address` and the `fields` components back to the source record, rather than keeping the original input. That is what gives you the standardisation benefit. An address that verifies but is never written back leaves the poor quality data in place.

## Error handling

Both adapters convert Loqate service conditions into faults that Oracle Integration can catch, so you can handle them in a scope with a fault handler rather than inspecting response codes yourself.

### GBG Loqate Reach

| Fault | Raised when |
| - | - |
| Unauthorized (401) | The Loqate API key is missing or was rejected |
| Invalid request (400) | The request to the verification service was malformed |
| Verification service error (502) | The upstream Loqate service returned an unexpected error |

### GBG Loqate Verify

| Fault | Raised when |
| - | - |
| Unauthorized (401) | The Loqate API key is missing or was rejected |
| No match (404) | The address could not be verified against reference data |
| Verification service error (502) | The Loqate Verify service returned an unexpected error |

> [!WARNING]
>
> The two adapters treat an unverifiable address differently. Verify raises a **No match (404)** fault, so an address that cannot be verified is an exception your flow must catch. Reach returns a normal response carrying a `reject` recommendation, so the same address flows through as data rather than as a fault. Design your error handling accordingly: with Reach you branch, with Verify you catch.

## Throughput

Each Verify address call verifies one address. To process many addresses in a single integration run, loop over your collection and call the action per record, keeping the usual Oracle Integration considerations in mind for large loops.

For bulk cleansing of large datasets, calling the [Loqate batch API](https://docs.loqate.com/api-reference/address-verify/quickstart) directly is more efficient than looping inside an integration, since it verifies many addresses per request.

## Troubleshooting

| Symptom | Likely cause | Resolution |
| - | - | - |
| Adapter missing from the Adapters list after installing | Catalogue cache not refreshed | Wait, or have an administrator force a catalogue refresh |
| ICS-18541 during installation | A privately registered adapter already uses the same identifier | Remove the private registration, then install from the Store |
| Connection test fails immediately | Endpoint unreachable from the instance, or endpoint URL edited | Restore the default endpoint and confirm outbound access to the host |
| Unauthorized (401) at runtime, though the test passed | Key revoked, expired, or out of entitlement since the test | Confirm the key is still valid and has remaining entitlement |
| Every address returns `reject` or a `U` status AVC | Wrong country code, so the address is matched against another country's reference data | Check the value being mapped into `country` |
| Verification service error (502) on every GBG Loqate Reach call | `country` is not mapped | Map `country`. Reach rejects a request without it |
| GBG Loqate Verify returns a blank address and no AVC, with no fault | `country` is not mapped | Map `country`. Without it the Verify service returns an empty match |
| Components come back empty but the address verified | The country's reference data does not populate that component | Compare against the [AVC](https://docs.loqate.com/report-codes/address-verification-code.md) match level rather than assuming a fault |
| No match (404) faults on addresses you expect to verify | New build, unusual format, or genuinely unverifiable input | Confirm with the same address through the Loqate API directly to isolate the adapter from the data |

## Support

For questions about the adapters or the Loqate service, email [LoqateSupport@gbgplc.com](mailto:LoqateSupport@gbgplc.com). Both adapters are published by GB Group plc.