Search
K
ARS — Address Resolution Service

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-15T02: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-005).
  • 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 plus the three
ISO 20022 identity sub-fields (addressType, department, subDepartment) 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
reasonsarray[object]

Structured reason code. Prefix indicates category (each family drawn from
the internal rules registry — clients should not depend on the exact
numeric value):
Customer-facing regulatory / processing families:
FMT = format-validation, FLD = field-required, REG = regulatory,
CNV = conversion, ENT = entity, VRF = verification.
Diagnostic / algorithmic families (INFO-severity only):
RFT = reformatting, INF = informational, DCT = dictionary match,
POS = positional-rule, SYN = syntax-rule, VLD = validation,
ENR = enrichment, ADP = adaptive-parser, DIC = dictionary lookup,
GLC = geo-location, PHN = phonetic, SPL = spell-correction,
VAL = validation-diagnostic.
All codes use the strict PREFIX-NNN (3-digit) format.

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 plus the three
ISO 20022 identity sub-fields (addressType, department, subDepartment) 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 (each family drawn from
the internal rules registry — clients should not depend on the exact
numeric value):
Customer-facing regulatory / processing families:
FMT = format-validation, FLD = field-required, REG = regulatory,
CNV = conversion, ENT = entity, VRF = verification.
Diagnostic / algorithmic families (INFO-severity only):
RFT = reformatting, INF = informational, DCT = dictionary match,
POS = positional-rule, SYN = syntax-rule, VLD = validation,
ENR = enrichment, ADP = adaptive-parser, DIC = dictionary lookup,
GLC = geo-location, PHN = phonetic, SPL = spell-correction,
VAL = validation-diagnostic.
All codes use the strict PREFIX-NNN (3-digit) format.

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

EP-04 — Convert Party Address (ARS AutoCorrect)

Converts a single party address to the requested target format.
OUTBOUND (default): SR2026 enforcement applies.
INBOUND: downgrade to FULLY_UNSTRUCTURED permitted — output is internal-use-only,
must never be re-injected into outgoing payment messages.

Business Rules:

  • C-01: targetFormat auto selects FULLY_STRUCTURED for __2 parties; HYBRID for SR2026 unstructured input.
  • C-02: FULLY_UNSTRUCTURED is never valid for __2 variant parties — HTTP 422.
  • C-03: OUTBOUND + SR2026 + post-cutover: FULLY_UNSTRUCTURED target rejected. INBOUND: skipped.
  • C-04: PMPG non-duplication enforced on all HYBRID outputs.
  • C-05: OUTBOUND fallback chain: FULLY_STRUCTURED → HYBRID → REJECT.
  • C-06: outputFormat ≠ targetFormat: WARNING explains fallback used.
  • C-07: Postal verification payload — address fields only; no names/BICs/IBANs/LEIs.
  • C-08: Input already at targetFormat → returned unchanged with confidence 1.0.
  • C-09: INBOUND HYBRID→UNSTRUCTURED: existing AdrLine preserved in lines 1–2.
  • C-10: INBOUND STRUCTURED→UNSTRUCTURED: all 14 fields rendered per PMPG §5 priority.
  • C-11: Truncation with PMPG ‘+’ marker at limit-1.
  • C-12: INBOUND downgrade always includes INFO issue marking result as internal-use-only.

Processing precedence: channelProfile → processingOptions → context.

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

Headers

X-Request-IDstring(uuid)

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

Body

ConvertPartyAddressRequest

EP-04 request. Format conversion to targetFormat.

channelNamestring
namestring

ISO 20022 party name. Used for entity conflict detection.

postalAddressobject

ISO 20022 PostalAddress24 object. All 14 structured fields plus the three
ISO 20022 identity sub-fields (addressType, department, subDepartment) 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
identificationobject

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

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

Conversion completed

ConvertPartyAddressResponse

statusstring

Outcome of AutoCorrect processing for an address.

Allowed values:VALIDATEDREPAIREDPARTIALLY_REPAIREDNOT_REPAIRED

successboolean

TRUE if conversion achieved target or fallback format. Preserved for backward compatibility.

inputFormatstring

Detected or target address format classification.

Allowed values:FULLY_STRUCTUREDHYBRIDFULLY_UNSTRUCTURED

outputFormatstring

Detected or target address format classification.

Allowed values:FULLY_STRUCTUREDHYBRIDFULLY_UNSTRUCTURED

correctedAddressobject

Corrected PostalAddress24 fields. null when status = NOT_REPAIRED.

Show Child Parameters
confidenceobject
Show Child Parameters
reasonsarray[object]

Structured reason code. Prefix indicates category (each family drawn from
the internal rules registry — clients should not depend on the exact
numeric value):
Customer-facing regulatory / processing families:
FMT = format-validation, FLD = field-required, REG = regulatory,
CNV = conversion, ENT = entity, VRF = verification.
Diagnostic / algorithmic families (INFO-severity only):
RFT = reformatting, INF = informational, DCT = dictionary match,
POS = positional-rule, SYN = syntax-rule, VLD = validation,
ENR = enrichment, ADP = adaptive-parser, DIC = dictionary lookup,
GLC = geo-location, PHN = phonetic, SPL = spell-correction,
VAL = validation-diagnostic.
All codes use the strict PREFIX-NNN (3-digit) format.

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
statisticsobject

Processing statistics block returned on all endpoints.

Show Child Parameters
outputobject

Extra output metadata about the conversion (format resolution, applied direction, target-format fallback trail).

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

Body

{ "channelName": "MY_SEPA_SCT", "name": "PETRA DUPONT", "postalAddress": { "addressLine": [ "CITY HALL GROTE MARKT 1", "1000 BRUSSELS" ], "country": "BE" }, "processingOptions": { "targetFormat": "HYBRID" } }