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" } }
 

EP-02 — Process Batch Party Address

Batch version of EP-01. Up to 1,000 transaction sets, each containing up to 10
party addresses (max 10,000 addresses per call). Each address processed independently.

Business Rules:

  • Requires HTTP Message Signature (RFC 9421) and Idempotency-Key header in production.
  • Each address processed independently — failure in one does not affect others.
  • Maximum: 1,000 transaction sets per call; 10 addresses per set.
  • PARTIAL_SUCCESS if at least one address accepted and at least one rejected.

Processing precedence: channelProfile → processingOptions → context.

post
https://api-uat.ionova.ai/ars/process-batch-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

Content-Digeststring

SHA-256 digest of the request body (RFC 9530). Required input for HTTP
Message Signature verification on this request. Optional in sandbox;
required in production for operations that mandate signing (see operation
description).

Signaturestring

HTTP Message Signature (RFC 9421) over the request, including the
Content-Digest header. Optional in sandbox; required in production for
operations that mandate signing (see operation description).

Signature-Inputstring

Signature metadata (RFC 9421) — identifies the signature algorithm,
covered components, and key identifier used to produce the Signature
header. Required whenever Signature is present.

Body

ProcessBatchPartyAddressRequest

EP-02 batch request. Up to 1,000 transaction sets per call.

channelNamestring
transactionSetsarray[object]required

<= 1000 items

Show Child Parameters
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]

Response

Batch processing completed

ProcessBatchPartyAddressResponse

decisionstring

Top-level processing decision.

Allowed values:ACCEPTREJECTPARTIAL_SUCCESS

statisticsobject

Processing statistics block returned on all endpoints.

Show Child Parameters
transactionSetsarray[object]
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-batch-party-address

Body

{ "channelName": "MY_SEPA_SCT", "transactionSets": [ { "transactionSetId": "SET-001", "addresses": [ { "postalAddress": { "streetName": "Rue de la Loi", "buildingNumber": "200", "postCode": "1040", "townName": "Brussels", "country": "BE" }, "context": { "partyRole": "debtor" } }, { "postalAddress": { "streetName": "Unter den Linden", "buildingNumber": "10", "postCode": "10117", "townName": "Berlin", "country": "DE" }, "context": { "partyRole": "creditor" } } ] } ] }
 

EP-03 — Check Party Address (ARS PreCheck)

Structural validation only — no postal DB lookup, no conversion. Sub-100ms.
Returns COMPLIANT or NOT_COMPLIANT with structured reason codes (FMT, FLD, REG prefixes).

v4.2 change: No longer performs postal database verification.
Pure structural validation only. Use EP-01 or EP-04 for postal verification.

Business Rules:

  • Does NOT perform postal DB verification.
  • Does NOT enforce cutover date-legality as a blocking action (flags REG-03 informationally).
  • partyRole defaults to debtor if omitted.
  • R-transaction message types return HTTP 422 REG-06.

Processing precedence: channelProfile → processingOptions → context.

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

Headers

X-Request-IDstring(uuid)

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

Body

CheckPartyAddressRequest

EP-03 request. Structural check only — no AutoCorrect repair.

channelNamestring
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 of PostalAddress. Alternative input format — clients
may supply either postalAddress (JSON) or postalAddressXml (XML tag names), not both.

Show Child Parameters
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

Response

Structural check completed

CheckPartyAddressResponse

statusstring

Outcome of structural pre-check validation.

Allowed values:COMPLIANTNOT_COMPLIANT

validboolean

TRUE if no structural errors. Preserved for backward compatibility.

formatstring

Detected or target address format classification.

Allowed values:FULLY_STRUCTUREDHYBRIDFULLY_UNSTRUCTURED

fieldResultsarray[object]

Per-field structural compliance detail.

Show Child Parameters
reasonsarray[object]

Structured reason code. Prefix indicates category:
FMT = format, FLD = field, REG = regulatory, ENT = entity, VRF = verification, CNV = conversion.

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
post/check-party-address

Body

{ "channelName": "MY_SEPA_SCT", "postalAddress": { "addressLine": [ "10 Unter den Linden", "10117 Berlin" ], "country": "DE" }, "context": { "partyRole": "creditor" } }