Search
K
ARS — Address Resolution Service

ARS — Address Resolution Service

4.3.1OAS 3.0

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

Payment Scheme Coverage

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

Category Schemes Scope
SEPA SCT, SCT_INST, SDD_CORE, SDD_B2B, OCT_INST 41 SEPA countries. Subject to the 22 Nov 2026 EPC address-format cutover.
Cross-border CBPRPLUS SWIFT CBPR+ global correspondent banking.
High-value / RTGS CHAPS, T2, EURO1, FEDWIRE UK, Eurozone, US high-value payment systems.
Other OTHER Extensible for additional domestic/regional schemes.

Three Editions, Four Market Segments

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

Edition Market Segment Core Challenge
ioNova ARS Treasury Corporate End-Users Ensure every outgoing address is compliant before the bank sees it. Clean beneficiary data at source.
ioNova ARS Banking Corporate Banks Gate-keep inbound payment files from clients AND correct addresses inline before entering the inter-PSP space.
ioNova ARS Transact Correspondent FIs, Transaction Banks Correct non-compliant addresses in transit without becoming a bottleneck in the payment chain. Provide compliance infrastructure to FI clients AND enforce address quality at the network boundary.

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

AutoCorrect vs PreCheck

Pattern Endpoints Decision values Use case
AutoCorrect Convert (EP-04, EP-12) ACCEPT, REJECT, PARTIAL_SUCCESS Correct addresses during processing — postal verification, entity extraction, normalisation. Start here.
PreCheck Check (EP-03, EP-10) COMPLIANT, NOT_COMPLIANT Structural validation only, no postal lookup. Sub-100ms. Use as a lightweight pre-filter or standalone compliance gate.
Full Pipeline Process (EP-01, EP-08) ACCEPT, REJECT, PARTIAL_SUCCESS Runs the complete 7-step pipeline: classify → validate → date-legality → normalise → verify → convert → revalidate.

Request Routing — Party vs Message

I have… I call… I get…
One extracted address /process-party-address One result
Many extracted addresses /process-batch-party-address Array of results
A complete ISO 20022 message /process-message-party-addresses All party addresses discovered + processed
Many complete messages /process-batch-message-party-addresses Array of message results

PostalAddress24 Variants

partyRole determines which XSD variant applies:

Variant Party Roles TownName / Country FULLY_UNSTRUCTURED allowed?
__1 debtor, creditor Optional Yes, INBOUND only, until the SR2026 cutover (2026-11-15T02:30:00Z); banned OUTBOUND post-cutover
__2 ultimate_debtor, ultimate_creditor, initiating_party Mandatory Never (REG-05)

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.

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

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

Version Summary
4.1.0 PreCheck/AutoCorrect patterns, status taxonomy, structured reason codes.
4.2.0 Consolidated release — all v4.1 enhancements integrated.
4.3.0 channelProfile model (early access), PARTIAL_SUCCESS decision added.
API Base URL
  • Server 1:https://api-uat.ionova.ai/ars

    UAT (test data only)

Security
ApiKeyAuth (apiKey)

Your ioNova platform API key. Generate it from your organisation admin in the ioNova app, then paste it here to test.

Additional Information
Contact ioNova Support (support@ionova.ai)

Layer 1 — Party Address

Single address in, single result out. Ideal for real-time form validation,
CRM import, and individual address remediation.

EP-01 — Process Party Address

Full 7-step pipeline on a single party address: classify → validate →
date-legality → normalise → verify (postal DB) → convert → revalidate.
Returns ACCEPT/REJECT with verification score, extracted identifiers, and full issue log.

partyRole is supplied via context.partyRole (or pre-configured in the
channelProfile’s channelSelection.partyRole) — it determines the PostalAddress24
XSD variant (__1 or __2), driving AdrLine limits and TownName/Country requirements.

Business Rules:

  • R-01: partyRole (resolved from context or channelProfile) determines PostalAddress24 variant (__1 or __2).
  • R-02: If executionDatetime ≥ 2026-11-22T02:30:00Z, SR2026 rules apply — FULLY_UNSTRUCTURED rejected.
  • R-03: For __2 parties (ultimate_debtor, ultimate_creditor, initiating_party),
    FULLY_UNSTRUCTURED is NEVER permitted — not even during grace period (REG-05).
  • R-04: BIC/LEI/IBAN in AddressLine extracted if identification field empty; conflict flagged but not moved.
  • R-05: TownName or Country in both structured fields AND AddressLine raises WARNING.
  • R-06: Only postal fields sent to postal DB — names, BICs, IBANs, LEIs excluded.

Processing precedence: channelProfile → processingOptions → context.

post
https://api-uat.ionova.ai/ars/process-party-address

Headers

X-Request-IDstring(uuid)

Client-supplied correlation ID echoed in response headers for tracing.

Idempotency-Keystring

Idempotency key for safe retry of POST requests. Duplicate submissions with the same key return the cached response.

<= 64 characters

Body

ProcessPartyAddressRequest

EP-01 request. Full ARS AutoCorrect processing on a single party address.
Processing precedence: channelProfile → processingOptions → context.

channelNamestring

Name of a registered channelProfile. Loads all channel defaults.

namestring

ISO 20022 party name. Used for entity conflict detection and name-in-address detection.

postalAddressobject

ISO 20022 PostalAddress24 object. All 14 structured fields are supported.
Country is strongly recommended for all submissions.
AddressLine is limited to max 7 elements in schema; practical publishing limits
are governed by OutputMode (EPC=2, CBPR_PLUS=3, MT_LEGACY=2, COMPLIANCE=7).
PMPG non-duplication rule: structured fields (TownName, Country) must NOT also
appear in AddressLine simultaneously.

Show Child Parameters
postalAddressXmlobject

ISO 20022 XML tag equivalents. Alternative to postalAddress.

Show Child Parameters
identificationobject

Optional party identifiers. Used for entity conflict detection (R-04).

Show Child Parameters
countryOfResidencestring

Match pattern:^[A-Z]{2}$

processingOptionsobject

Per-request overrides of the channelProfile configuration. Only fields present
here override the corresponding channelProfile value. Fields absent here fall
through to channelProfile. This is NOT a general-purpose configuration block —
it only overrides values already set in channelProfile.

Show Child Parameters
contextobject

Analytics/audit passthrough AND processing fallback layer.
Fields labelled “Analytics + Processing fallback” are used as last-resort defaults
when both channelProfile and processingOptions leave a parameter unresolved.
Pure analytics fields are written to the ARS audit log but do not affect processing.
Processing precedence: channelProfile → processingOptions → context.

Show Child Parameters
includearray[string]

Optional response enrichment fields.

Allowed values:canonicaltraceabilityactions

Response

Processing completed

ProcessPartyAddressResponse

decisionstring

Top-level processing decision.

Allowed values:ACCEPTREJECTPARTIAL_SUCCESS

resultobject

Full address processing result object (used in EP-01 and all Layer 1 responses).

Show Child Parameters
statisticsobject

Processing statistics block returned on all endpoints.

Show Child Parameters
issuesarray[object]

Legacy issue object. Preserved for backward compatibility with v4.0 integrations.
New integrations should use reasons[] instead.

Show Child Parameters
timestampstring(date-time)
post/process-party-address

Body

{ "channelName": "MY_SEPA_SCT", "postalAddress": { "streetName": "Unter den Linden", "buildingNumber": "10", "postCode": "10117", "townName": "Berlin", "country": "DE" }, "processingOptions": { "quality": "premium", "targetFormat": "FULLY_STRUCTURED" }, "context": { "partyRole": "creditor", "source": "PAYMENT_HUB", "reference": "TXN-20261015-001" } }