The Address Resolution Service (ARS) v4.3 provides ISO 20022 postal address
validation, classification, conversion, rendering, and compliance assessment
across 27 endpoints organised into 5 functional layers.

Payment Scheme Coverage

ARS supports 11 payment schemes across SEPA, cross-border, and high-value
payment systems:

Three Editions, Four Market Segments

The same 27-endpoint API is packaged into three named editions, each
targeting specific market segments with segment-specific defaults,
assurance levels, and positioning:

All three editions use the identical API surface. The edition determines
default configuration (scheme, assurance level) — not which endpoints are
available.

AutoCorrect vs PreCheck

Request Routing — Party vs Message

PostalAddress24 Variants

partyRole determines which XSD variant applies:

Status Taxonomy

AutoCorrect (AutoCorrectStatus, address-level): VALIDATED (already
compliant), REPAIRED (corrected, confidence ≥ threshold),
PARTIALLY_REPAIRED (corrected, confidence < threshold), NOT_REPAIRED
(cannot be corrected — manual intervention required).

PreCheck (PreCheckStatus): COMPLIANT, NOT_COMPLIANT.

Top-level Decision: ACCEPT, REJECT, PARTIAL_SUCCESS — the overall
outcome returned by Process and Convert endpoints, derived from the
per-address statuses above.

Parameter Reference

Complete request structure showing every supported field in its correct
hierarchy. All fields are optional unless noted. Use this skeleton to
understand nesting before consulting the per-field tables below.

{
  "channelName": "MY_SEPA_SCT",
  "name": "PETRA DUPONT",
  "postalAddress": {
    "addressLine": ["Hoogstraat 6", "1000 Brussels"],
    "streetName": "...",
    "buildingNumber": "...",
    "buildingName": "...",
    "floor": "...",
    "postBox": "...",
    "room": "...",
    "postCode": "...",
    "townName": "...",
    "townLocationName": "...",
    "districtName": "...",
    "countrySubDivision": "...",
    "country": "DE",
    "countryOfResidence": "DE"
  },
  "postalAddressXml": {
    "AdrLine": ["Hoogstraat 6", "1000 Brussels"],
    "StrtNm": "...", "BldgNb": "...", "BldgNm": "...",
    "Flr": "...", "PstBx": "...", "Room": "...",
    "PstCd": "...", "TwnNm": "...", "TwnLctnNm": "...",
    "DstrctNm": "...", "CtrySubDvsn": "...",
    "Ctry": "DE", "CtryOfRes": "DE"
  },
  "identification": {
    "organisationId": {
      "anyBic": "DEUTDEFF",
      "lei": "529900T8BM49AURSDO55",
      "other": "..."
    },
    "privateId": {
      "other": "PASSPORT-DE-123456"
    }
  },
  "countryOfResidence": "DE",
  "processingOptions": {
    "scheme": "SCT",
    "schemeVersion": "SR2026",
    "quality": "premium",
    "verification": true,
    "detectMisplacedIdentifiers": true,
    "validateNameContent": true,
    "redaction": "NONE",
    "targetFormat": "FULLY_STRUCTURED",
    "repairConfidenceThreshold": 0.85,
    "payerPspCountry": "DE",
    "payeePspCountry": "BE"
  },
  "context": {
    "scheme": "SCT",
    "schemeVersion": "SR2025",
    "executionDatetime": "2026-10-15T10:30:00Z",
    "direction": "OUTBOUND",
    "partyRole": "creditor",
    "outputMode": "EPC",
    "sendingCountry": "DE",
    "receivingCountry": "BE",
    "messageType": "pacs.008",
    "timezone": "Europe/Berlin",
    "name": "PETRA DUPONT",
    "inputFormat": "FULLY_UNSTRUCTURED",
    "outputFormat": "FULLY_STRUCTURED",
    "source": "PAYMENT_HUB",
    "sender": "DEUTDEFF",
    "receiver": "BNPAFRPP",
    "paymentMethod": "TRF",
    "channel": "api",
    "application": "SWIFT_ALLIANCE_GATEWAY",
    "reference": "TXN-20261015-001",
    "partyType": "COMPANY"
  },
  "include": ["canonical", "traceability", "actions"]
}

Note: postalAddress and postalAddressXml are mutually exclusive —
submit one or the other, not both. postalAddress uses camelCase field
names (JSON-native); postalAddressXml uses ISO 20022 tag names directly.

PostalAddress24 Fields

All fields optional. See PostalAddress24 Variants above for __1/__2 rules.

processingOptions Fields

Per-request overrides of the active channelProfile. All optional.

context Fields — Processing Fallback

Used as last-resort fallback when channelProfile and processingOptions do
not supply a value. Also always written to the audit trail.

context Fields — Analytics Only

Written to the audit trail on every call. No effect on processing outcome.

identification Fields

Optional top-level field on processing requests. Used for entity conflict
detection (rule R-04). Submit organisationId OR privateId, not both.

Standards

ISO 20022 | EPC153-22 v2.1 | PMPG Hybrid Postal Address v1.12 |
PMPG Grace Period Guide | CBPRPlus SR2025 | EU Regulation 2023/1113

Content Types

All POST endpoints accept and return application/json (primary) and
application/xml (ISO 20022 native format). GET endpoints return
application/json only.
When using XML: Content-Type: application/xml, Accept: application/xml.

Security

• Transport: TLS 1.2+ mandatory.
• Authentication: JWT Bearer (RS256/PS256) + API Key — dual factor,
  OAuth 2.0 Client Credentials grant.
• Correlation: X-Request-ID + Idempotency-Key on every write request.
• Integrity: HTTP Message Signatures (RFC 9421) over Content-Digest
  (RFC 9530) — required in production on batch and R-transaction message
  endpoints, optional elsewhere.
• Data handling: no address content persisted beyond the request lifecycle.

Authentication

All endpoints (except /health) require dual authentication:

• Authorization: Bearer <JWT> — OAuth 2.0 bearer token
• apikey: <api-key> — API key as second factor (Kong key-auth header)

Processing Precedence

ARS resolves processing parameters using a three-tier model:

1. channelProfile (primary) — loaded via channelName; establishes all defaults
   for this channel/scheme/direction combination. (Channel profile management,
   EP-25/26/27, is in early access and not yet generally available.)
2. processingOptions (override) — per-request deviations from channelProfile.
   Sole function: modify specific channelProfile values for one request only.
3. context (fallback + analytics) — last-resort fallback for any unresolved
   parameter; all context fields always written to the audit trail.

Version History