Search
K
ARS — Address Resolution Service

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

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 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:
FMT = format, FLD = field, REG = regulatory, ENT = entity, VRF = verification, CNV = conversion.

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

EP-05 — Render Party Address

Renders a structured or hybrid address into AddressLine-only format following
PMPG Section 5 mapping priorities. Country always preserved separately.

PMPG mapping priority:

  • Line 1 (street-level): StreetName+BuildingNumber, BuildingName, Floor, PostBox, Room, Department, SubDepartment.
  • Line 2 (locality): PostCode+TownName, CountrySubDivision, TownLocationName, DistrictName.
  • Country: always output separately — never embedded in rendered lines.

For MT RTGS compatibility: maxLines=3, maxLineLength=35.

Processing precedence: channelProfile → processingOptions → context.

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

Headers

X-Request-IDstring(uuid)

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

Body

RenderPartyAddressRequest

EP-05 request. Formats address into unstructured lines per OutputMode limits.

channelNamestring
namestring

ISO 20022 party name. Included in rendered output when present.

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
maxLinesinteger

Maximum output lines. Overrides channelProfile format limits.

maxLineLengthinteger

Maximum chars per output line. Overrides channelProfile. Default 35.

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

Rendering completed

RenderPartyAddressResponse

decisionstring

Allowed values:ACCEPTPARTIAL_SUCCESS

resultobject
Show Child Parameters
statisticsobject

Processing statistics block returned on all endpoints.

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

Body

{ "channelName": "MY_SEPA_SCT", "name": "JOHN SMITH", "postalAddress": { "streetName": "Hoogstraat", "buildingNumber": "6", "floor": "18th Floor", "postCode": "1000", "townName": "Brussels", "country": "BE" }, "maxLines": 2, "maxLineLength": 70 }
 

EP-06 — Classify Party Address

Lightest available endpoint. Returns format classification only — no validation,
verification, conversion, or normalisation. Extremely low latency.

Classification logic:

  • FULLY_STRUCTURED: Country + TownName present AND no AddressLine.
  • HYBRID: Country + TownName present AND AddressLine present.
  • FULLY_UNSTRUCTURED: anything else.

No issues[] or reasons[] in response. Context fields are analytics only.

Processing precedence: channelProfile → processingOptions → context.

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

Headers

X-Request-IDstring(uuid)

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

Body

ClassifyPartyAddressRequest

EP-06 request. Lightweight classification only — no 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
contextobject

Analytics only for this endpoint — no processing fallback.

Show Child Parameters

Response

Classification completed

ClassifyPartyAddressResponse

formatstring

Detected or target address format classification.

Allowed values:FULLY_STRUCTUREDHYBRIDFULLY_UNSTRUCTURED

hasAddressLineboolean
addressLineCountinteger
hasStructuredFieldsboolean
hasTownNameboolean
hasCountryboolean
post/classify-party-address

Body

{ "postalAddress": { "postCode": "1000", "townName": "Brussels", "country": "BE", "addressLine": [ "CITY HALL GROTE MARKT 1" ] } }