27 endpoints · 5 groups
API reference
Every endpoint is a verb — Process, Check, Convert, Classify, Render, Extract — applied at one of two scopes. Learn the verbs once; the rest is predictable.
ARS — Address Resolution Service
4.3.1
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 15 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-005) |
## 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.
```json
{
"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.*
| Field | ISO Tag | Max | Notes | Example |
|---|---|---|---|---|
| addressLine | AdrLine | 7 × 70 chars | Unstructured lines. Max 3 for __1 parties; max 2 for __2. Must not duplicate structured fields (PMPG non-duplication rule). | `["Hoogstraat 6", "1000 Brussels"]` |
| streetName | StrtNm | 70 | | `"Unter den Linden"` |
| buildingNumber | BldgNb | 16 | | `"10"` |
| buildingName | BldgNm | 35 | | `"Premium Tower"` |
| floor | Flr | 70 | | `"18th Floor"` |
| postBox | PstBx | 16 | | `"PO Box 12"` |
| room | Room | 70 | | `"Suite 301"` |
| postCode | PstCd | 16 | | `"10117"` |
| townName | TwnNm | 35 | Mandatory for __2 parties. Best practice for all. | `"Berlin"` |
| townLocationName | TwnLctnNm | 35 | | `"Mitte"` |
| districtName | DstrctNm | 35 | | `"Charlottenburg"` |
| countrySubDivision | CtrySubDvsn | 35 | | `"Bavaria"` |
| country | Ctry | 2 | ISO 3166-1 alpha-2. Strongly recommended. Mandatory for __2 parties. | `"DE"` |
| countryOfResidence | CtryOfRes | 2 | ISO 3166-1 alpha-2. Residential country — distinct from postal address country. | `"DE"` |
### processingOptions Fields
*Per-request overrides of the active channelProfile. All optional.*
| Field | Type / Enum | Description | Example |
|---|---|---|---|
| scheme | `SCT` `SCT_INST` `SDD_CORE` `SDD_B2B` `OCT_INST` `CBPRPLUS` `CHAPS` `T2` `EURO1` `FEDWIRE` `OTHER` | Override payment scheme for this request only. | `"SCT_INST"` |
| schemeVersion | `SR2025` `SR2026` | Override scheme version. Controls SR2026 cutover date enforcement. | `"SR2026"` |
| quality | `premium` `standard` `basic` | Override verification depth. `premium` = full postal DB. `basic` = structural only. | `"premium"` |
| verification | boolean | When `false`, skips postal DB lookup regardless of quality. Forced `false` when quality = basic. | `false` |
| detectMisplacedIdentifiers | boolean | When `true`, flags BIC/LEI/IBAN found inside AddressLine fields (rule R-04). | `true` |
| validateNameContent | boolean | When `true`, checks for party name duplication inside address lines. | `true` |
| redaction | `NONE` `PARTIAL` `FULL` | PII redaction level applied to address fields in the response. | `"PARTIAL"` |
| targetFormat | `auto` `FULLY_STRUCTURED` `HYBRID` `FULLY_UNSTRUCTURED` | Override target output format. `auto` = ARS selects best achievable. | `"FULLY_STRUCTURED"` |
| repairConfidenceThreshold | number 0.0–1.0 | Minimum confidence score to promote PARTIALLY_REPAIRED to REPAIRED. | `0.85` |
| payerPspCountry | ISO 3166-1 alpha-2 | Payer PSP country — used for EPC SEPA compliance threshold. | `"DE"` |
| payeePspCountry | ISO 3166-1 alpha-2 | Payee PSP country — used for EPC SEPA compliance threshold. | `"BE"` |
### 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.*
| Field | Type / Enum | Description | Example |
|---|---|---|---|
| scheme | `SCT` `SCT_INST` `SDD_CORE` `SDD_B2B` `OCT_INST` `CBPRPLUS` `CHAPS` `T2` `EURO1` `FEDWIRE` `OTHER` | Fallback payment scheme. | `"SCT"` |
| schemeVersion | `SR2025` `SR2026` | Fallback scheme version. Controls SR2026 cutover enforcement. | `"SR2025"` |
| executionDatetime | ISO 8601 UTC string | Payment execution datetime. Used for SR2026 cutover date checks. | `"2026-10-15T10:30:00Z"` |
| direction | `OUTBOUND` `INBOUND` | Payment direction. OUTBOUND = sending; INBOUND = receiving. | `"OUTBOUND"` |
| partyRole | `debtor` `creditor` `ultimate_debtor` `ultimate_creditor` `initiating_party` | Party role — determines PostalAddress24 variant (__1 or __2). | `"creditor"` |
| outputMode | `EPC` `CBPR_PLUS` `MT_LEGACY` `COMPLIANCE` | Address line rendering constraints per channel type. | `"EPC"` |
| sendingCountry | ISO 3166-1 alpha-2 | Country of the sending PSP. | `"DE"` |
| receivingCountry | ISO 3166-1 alpha-2 | Country of the receiving PSP. | `"BE"` |
| messageType | `pacs.008` `pacs.009` `camt.056` ... (26 types) | ISO 20022 message type. | `"pacs.008"` |
| timezone | IANA timezone string | Timezone for executionDatetime evaluation. | `"Europe/Berlin"` |
### context Fields — Analytics Only
*Written to the audit trail on every call. No effect on processing outcome.*
| Field | Type / Enum | Description | Example |
|---|---|---|---|
| name | string | Party name for entity conflict analytics. | `"PETRA DUPONT"` |
| inputFormat | `FULLY_STRUCTURED` `HYBRID` `FULLY_UNSTRUCTURED` | Format of the originating input, for audit. | `"FULLY_UNSTRUCTURED"` |
| outputFormat | `FULLY_STRUCTURED` `HYBRID` `FULLY_UNSTRUCTURED` | Expected output format, for audit. | `"FULLY_STRUCTURED"` |
| source | string | Sending system identifier. | `"PAYMENT_HUB"` |
| sender | string | BIC of the sending institution. | `"DEUTDEFF"` |
| receiver | string | BIC of the receiving institution. | `"BNPAFRPP"` |
| paymentMethod | string | Payment method for audit reporting. | `"TRF"` |
| channel | `api` `file` `other` | Delivery channel for audit. | `"api"` |
| application | string | Caller application identifier. | `"SWIFT_ALLIANCE_GATEWAY"` |
| reference | string | Business reference for audit trail (payment ID, batch ID, etc.). | `"TXN-20261015-001"` |
| partyType | `COMPANY` `INDIVIDUAL` | Whether the party is a company or individual. | `"COMPANY"` |
### identification Fields
*Optional top-level field on processing requests. Used for entity conflict
detection (rule R-04). Submit organisationId OR privateId, not both.*
| Field | Path | ISO Tag | Description | Example |
|---|---|---|---|---|
| anyBic | identification.organisationId.anyBic | OrgId/AnyBIC | BIC (8 or 11 chars). | `"DEUTDEFF"` |
| lei | identification.organisationId.lei | OrgId/LEI | Legal Entity Identifier (20 chars). | `"529900T8BM49AURSDO55"` |
| other | identification.organisationId.other | OrgId/Othr | Other organisation identifier. | `"DE12345678"` |
| other | identification.privateId.other | PrvtId/Othr | Private individual identifier. | `"PASSPORT-DE-123456"` |
## 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. |