---
title: "EP-01 — Process Party Address"
url: "https://dev.ionova.ai/apis/ars-address-resolution-service-4/versions/fdd2c316-7f84-4f04-8bb7-64e9bf97893b/operations/processPartyAddress"
---

> Full API specification: https://dev.ionova.ai/apis/ars-address-resolution-service-4/versions/fdd2c316-7f84-4f04-8bb7-64e9bf97893b.md

# EP-01 — Process Party Address

`POST` `/process-party-address`

Operation ID: `processPartyAddress`

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.

## Header parameters

- `X-Request-ID` (string, uuid, optional) - Client-supplied correlation ID echoed in response headers for tracing.
- `Idempotency-Key` (string, optional) - Idempotency key for safe retry of POST requests. Duplicate submissions with the same key return the cached response.

## Request body (required)

Content types: `application/json`, `application/xml`

## Responses

- `200` - Processing completed
- `400` - Bad Request — malformed request body or invalid parameter.
- `401` - Unauthorized — missing or invalid authentication credentials.
- `422` - Unprocessable Entity — semantic validation failure (e.g. R-transaction type submitted to a non-R endpoint).
- `429` - Too Many Requests — rate limit exceeded.
- `500` - Internal Server Error — unexpected server-side failure.

## OpenAPI definition

```yaml
openapi: 3.0.3
info:
  title: ARS — Address Resolution Service
  version: 4.3.1
servers:
  - url: https://api-uat.ionova.ai/ars
    description: UAT (test data only)
paths:
  /process-party-address:
    post:
      tags:
        - Layer 1 — Party Address
      summary: EP-01 — Process Party Address
      description: >
        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.
      operationId: processPartyAddress
      parameters:
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessPartyAddressRequest"
            example:
              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
          application/xml:
            schema:
              $ref: "#/components/schemas/ProcessPartyAddressRequest"
            example: |
              <ProcessPartyAddressRequest>
                <channelName>MY_SEPA_SCT</channelName>
                <PstlAdr>
                  <StrtNm>Unter den Linden</StrtNm>
                  <BldgNb>10</BldgNb>
                  <PstCd>10117</PstCd>
                  <TwnNm>Berlin</TwnNm>
                  <Ctry>DE</Ctry>
                </PstlAdr>
                <processingOptions>
                  <quality>premium</quality>
                  <targetFormat>FULLY_STRUCTURED</targetFormat>
                </processingOptions>
                <context>
                  <partyRole>creditor</partyRole>
                  <source>PAYMENT_HUB</source>
                  <reference>TXN-20261015-001</reference>
                </context>
              </ProcessPartyAddressRequest>
      responses:
        "200":
          description: Processing completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessPartyAddressResponse"
            application/xml:
              schema:
                $ref: "#/components/schemas/ProcessPartyAddressResponse"
              example: |
                <ProcessPartyAddressResponse>
                  <decision>ACCEPT</decision>
                  <result>
                    <partyRole>creditor</partyRole>
                    <inputFormat>FULLY_STRUCTURED</inputFormat>
                    <outputFormat>FULLY_STRUCTURED</outputFormat>
                    <status>VALIDATED</status>
                    <PstlAdr>
                      <StrtNm>Unter den Linden</StrtNm>
                      <BldgNb>10</BldgNb>
                      <PstCd>10117</PstCd>
                      <TwnNm>Berlin</TwnNm>
                      <Ctry>DE</Ctry>
                    </PstlAdr>
                    <verification>
                      <status>verified</status>
                      <score>0.98</score>
                    </verification>
                  </result>
                  <statistics>
                    <processingTimeMs>45</processingTimeMs>
                    <totalRecords>1</totalRecords>
                    <acceptedRecords>1</acceptedRecords>
                  </statistics>
                  <timestamp>2026-10-15T10:30:00Z</timestamp>
                </ProcessPartyAddressResponse>
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - ApiKeyAuth: []
security:
  - ApiKeyAuth: []
components:
  parameters:
    XRequestId:
      name: X-Request-ID
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: Client-supplied correlation ID echoed in response headers for tracing.
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 64
      description: Idempotency key for safe retry of POST requests. Duplicate
        submissions with the same key return the cached response.
  schemas:
    ProcessPartyAddressRequest:
      type: object
      description: >
        EP-01 request. Full ARS AutoCorrect processing on a single party
        address.

        Processing precedence: channelProfile → processingOptions → context.
      xml:
        name: ProcessPartyAddressRequest
      properties:
        channelName:
          type: string
          description: Name of a registered channelProfile. Loads all channel defaults.
        name:
          type: string
          description: ISO 20022 party name. Used for entity conflict detection and
            name-in-address detection.
          xml:
            name: Nm
        postalAddress:
          allOf:
            - $ref: "#/components/schemas/PostalAddress"
          xml:
            name: PstlAdr
        postalAddressXml:
          allOf:
            - $ref: "#/components/schemas/PostalAddressXml"
          description: ISO 20022 XML tag equivalents. Alternative to postalAddress.
          xml:
            name: PstlAdr
        identification:
          allOf:
            - $ref: "#/components/schemas/Identification"
          xml:
            name: Id
        countryOfResidence:
          type: string
          pattern: ^[A-Z]{2}$
          xml:
            name: CtryOfRes
        processingOptions:
          $ref: "#/components/schemas/ProcessingOptions"
        context:
          $ref: "#/components/schemas/Context"
        include:
          type: array
          items:
            type: string
            enum:
              - canonical
              - traceability
              - actions
          description: Optional response enrichment fields.
    ProcessPartyAddressResponse:
      type: object
      xml:
        name: ProcessPartyAddressResponse
      properties:
        decision:
          $ref: "#/components/schemas/Decision"
        result:
          $ref: "#/components/schemas/AddressResult"
        statistics:
          $ref: "#/components/schemas/Statistics"
        issues:
          type: array
          items:
            $ref: "#/components/schemas/Issue"
          description: Ordered issue list. Preserved for backward compatibility.
        timestamp:
          type: string
          format: date-time
    PostalAddress:
      type: object
      description: >
        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.
      properties:
        addressLine:
          type: array
          items:
            type: string
            maxLength: 70
          maxItems: 7
          description: Unstructured address lines (max 70 chars each). Max 3 for __1
            variant parties, max 2 for __2 variant parties.
          xml:
            name: AdrLine
            wrapped: false
        streetName:
          type: string
          maxLength: 70
          xml:
            name: StrtNm
        buildingNumber:
          type: string
          maxLength: 16
          xml:
            name: BldgNb
        buildingName:
          type: string
          maxLength: 35
          xml:
            name: BldgNm
        floor:
          type: string
          maxLength: 70
          xml:
            name: Flr
        postBox:
          type: string
          maxLength: 16
          xml:
            name: PstBx
        room:
          type: string
          maxLength: 70
          xml:
            name: Room
        postCode:
          type: string
          maxLength: 16
          xml:
            name: PstCd
        townName:
          type: string
          maxLength: 35
          description: Required for __2 variant parties (ultimate_debtor,
            ultimate_creditor, initiating_party). Best practice for all.
          xml:
            name: TwnNm
        townLocationName:
          type: string
          maxLength: 35
          xml:
            name: TwnLctnNm
        districtName:
          type: string
          maxLength: 35
          xml:
            name: DstrctNm
        countrySubDivision:
          type: string
          maxLength: 35
          xml:
            name: CtrySubDvsn
        country:
          type: string
          pattern: ^[A-Z]{2}$
          description: ISO 3166-1 alpha-2. Strongly recommended. Required for __2 variant
            parties.
          xml:
            name: Ctry
        countryOfResidence:
          type: string
          pattern: ^[A-Z]{2}$
          description: ISO 3166-1 alpha-2. Country where the party is resident. Distinct
            from country in the postal address.
          xml:
            name: CtryOfRes
    PostalAddressXml:
      type: object
      description: >
        ISO 20022 XML tag equivalents of PostalAddress. Alternative input format
        — clients

        may supply either postalAddress (JSON) or postalAddressXml (XML tag
        names), not both.
      properties:
        AdrLine:
          type: array
          items:
            type: string
            maxLength: 70
          maxItems: 7
          xml:
            wrapped: false
        StrtNm:
          type: string
          maxLength: 70
        BldgNb:
          type: string
          maxLength: 16
        BldgNm:
          type: string
          maxLength: 35
        Flr:
          type: string
          maxLength: 70
        PstBx:
          type: string
          maxLength: 16
        Room:
          type: string
          maxLength: 70
        PstCd:
          type: string
          maxLength: 16
        TwnNm:
          type: string
          maxLength: 35
        TwnLctnNm:
          type: string
          maxLength: 35
        DstrctNm:
          type: string
          maxLength: 35
        CtrySubDvsn:
          type: string
          maxLength: 35
        Ctry:
          type: string
          pattern: ^[A-Z]{2}$
        CtryOfRes:
          type: string
          pattern: ^[A-Z]{2}$
    Identification:
      type: object
      description: Optional party identifiers. Used for entity conflict detection (R-04).
      properties:
        organisationId:
          type: object
          xml:
            name: OrgId
          properties:
            anyBic:
              type: string
              description: BIC (8 or 11 chars).
              xml:
                name: AnyBIC
            lei:
              type: string
              description: Legal Entity Identifier (20 chars).
              xml:
                name: LEI
            other:
              type: string
              description: Other organisation identifier.
              xml:
                name: Othr
        privateId:
          type: object
          xml:
            name: PrvtId
          properties:
            other:
              type: string
              description: Private individual identifier.
              xml:
                name: Othr
    ProcessingOptions:
      type: object
      xml:
        name: ProcessingOptions
      description: >
        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.
      properties:
        scheme:
          allOf:
            - $ref: "#/components/schemas/SchemeCode"
          description: Per-request override of channelProfile.scheme.
        schemeVersion:
          allOf:
            - $ref: "#/components/schemas/SchemeVersion"
          description: Per-request override of channelProfile.schemeVersion. SR2025 or
            SR2026.
        quality:
          allOf:
            - $ref: "#/components/schemas/Quality"
          description: Per-request override of channelProfile.quality.
        verification:
          type: boolean
          description: Per-request override. When false, skips postal DB lookup. Forced
            false for Basic quality.
        detectMisplacedIdentifiers:
          type: boolean
          description: Per-request override. When true, flags BIC/LEI/IBAN found in
            AddressLine (R-04).
        validateNameContent:
          type: boolean
          description: Per-request override. When true, checks for party name duplication
            in address lines (R-05).
        redaction:
          type: string
          enum:
            - NONE
            - PARTIAL
            - FULL
          description: Per-request override. PII redaction level applied to response
            address fields.
        targetFormat:
          allOf:
            - $ref: "#/components/schemas/TargetFormat"
          description: Per-request override of channelProfile default targetFormat.
        repairConfidenceThreshold:
          type: number
          minimum: 0
          maximum: 1
          description: Per-request override of channelProfile.repairConfidenceThreshold
            (0.0–1.0).
        payerPspCountry:
          type: string
          pattern: ^[A-Z]{2}$
          description: Per-request override of channelProfile.payerPspCountry. ISO 3166-1
            alpha-2.
        payeePspCountry:
          type: string
          pattern: ^[A-Z]{2}$
          description: Per-request override of channelProfile.payeePspCountry. ISO 3166-1
            alpha-2.
    Context:
      type: object
      xml:
        name: Context
      description: >
        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.
      properties:
        name:
          type: string
          description: Analytics only. ISO 20022 party name used for entity conflict
            detection.
        scheme:
          allOf:
            - $ref: "#/components/schemas/SchemeCode"
          description: Analytics + Processing fallback. Payment scheme.
        schemeVersion:
          allOf:
            - $ref: "#/components/schemas/SchemeVersion"
          description: Analytics + Processing fallback. SR2025 or SR2026. Controls
            post-cutover enforcement.
        executionDatetime:
          type: string
          format: date-time
          description: Analytics + Processing fallback. Payment execution datetime in ISO
            8601 UTC. Used for SR2026 cutover enforcement (cutover =
            2026-11-22T02:30:00Z).
        direction:
          allOf:
            - $ref: "#/components/schemas/Direction"
          description: Analytics + Processing fallback. OUTBOUND | INBOUND.
        partyRole:
          allOf:
            - $ref: "#/components/schemas/PartyRole"
          description: Analytics + Processing fallback. Party role for this request.
        outputMode:
          allOf:
            - $ref: "#/components/schemas/OutputMode"
          description: Analytics + Processing fallback. Address line rendering constraints.
        sendingCountry:
          type: string
          pattern: ^[A-Z]{2}$
          description: Analytics + Processing fallback. Country of the sending PSP (ISO
            3166-1 alpha-2).
        receivingCountry:
          type: string
          pattern: ^[A-Z]{2}$
          description: Analytics + Processing fallback. Country of the receiving PSP.
        messageType:
          allOf:
            - $ref: "#/components/schemas/MessageType"
          description: Analytics + Processing fallback. ISO 20022 message type.
        timezone:
          type: string
          description: Analytics + Processing fallback. IANA timezone for
            executionDatetime evaluation.
        inputFormat:
          allOf:
            - $ref: "#/components/schemas/AddressFormat"
          description: Analytics only. Format of the originating input.
        outputFormat:
          allOf:
            - $ref: "#/components/schemas/AddressFormat"
          description: Analytics only. Expected output format.
        source:
          type: string
          description: Analytics only. Sending system identifier (e.g. PAYMENT_HUB,
            SWIFT_ALLIANCE).
        sender:
          type: string
          description: Analytics only. BIC of the sending institution.
        receiver:
          type: string
          description: Analytics only. BIC of the receiving institution.
        paymentMethod:
          type: string
          description: Analytics only. Payment method for audit reporting.
        channel:
          allOf:
            - $ref: "#/components/schemas/ChannelType"
          description: Analytics only. Delivery channel for audit.
        application:
          type: string
          description: Analytics only. Caller application identifier.
        reference:
          type: string
          description: Analytics only. Business reference for audit trail (e.g. payment
            ID, batch ID).
        partyType:
          type: string
          enum:
            - COMPANY
            - INDIVIDUAL
          description: Analytics only. Whether the party is a company or individual.
    Decision:
      type: string
      description: Top-level processing decision.
      enum:
        - ACCEPT
        - REJECT
        - PARTIAL_SUCCESS
    AddressResult:
      type: object
      description: Full address processing result object (used in EP-01 and all Layer
        1 responses).
      xml:
        name: AddressResult
      properties:
        partyRole:
          $ref: "#/components/schemas/PartyRole"
        inputFormat:
          allOf:
            - $ref: "#/components/schemas/AddressFormat"
          description: Format detected in the submitted address.
        outputFormat:
          allOf:
            - $ref: "#/components/schemas/AddressFormat"
          description: Format of the processed output address.
        status:
          $ref: "#/components/schemas/AutoCorrectStatus"
        output:
          allOf:
            - $ref: "#/components/schemas/PostalAddress"
          description: Processed PostalAddress24 output.
          xml:
            name: PstlAdr
        verification:
          type: object
          description: Postal DB verification result.
          properties:
            status:
              type: string
              enum:
                - verified
                - partial
                - unverified
            score:
              type: number
              minimum: 0
              maximum: 1
        extractedIdentifiers:
          type: object
          description: Identifiers extracted from AddressLine (R-04 entity extraction).
          properties:
            bic:
              type: string
            lei:
              type: string
            iban:
              type: string
        detectedNameInAddress:
          type: string
          description: Party name text found embedded within address lines (R-05 PMPG
            non-duplication).
        confidence:
          type: object
          description: Overall confidence score (0.0–1.0) and per-field confidence scores.
          properties:
            overall:
              type: number
              minimum: 0
              maximum: 1
            fields:
              type: object
              additionalProperties:
                type: number
        canonical:
          type: object
          description: Canonical normalised address and SHA-256 fingerprint. Present when
            `include` contains `canonical`.
          properties:
            address:
              $ref: "#/components/schemas/PostalAddress"
            fingerprint:
              type: string
              description: SHA-256 hash of the canonical address for deduplication.
        rTransactionExempt:
          type: boolean
          description: TRUE if this address is exempt from SR2026 enforcement under EPC
            §8.3.
        reasons:
          type: array
          items:
            $ref: "#/components/schemas/ReasonCode"
    Statistics:
      type: object
      xml:
        name: Statistics
      description: Processing statistics block returned on all endpoints.
      properties:
        processingTimeMs:
          type: integer
          description: Total processing time in milliseconds.
        totalRecords:
          type: integer
          description: Total number of records submitted.
        processedRecords:
          type: integer
          description: Number of records successfully processed.
        acceptedCount:
          type: integer
        rejectedCount:
          type: integer
    Issue:
      type: object
      xml:
        name: Issue
      description: >
        Legacy issue object. Preserved for backward compatibility with v4.0
        integrations.

        New integrations should use reasons[] instead.
      properties:
        severity:
          type: string
          enum:
            - ERROR
            - WARNING
            - INFO
        code:
          type: string
        message:
          type: string
        field:
          type: string
    ErrorResponse:
      type: object
      xml:
        name: ErrorResponse
      description: Standard error envelope returned on 4xx and 5xx responses.
      properties:
        code:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Human-readable error description.
        requestId:
          type: string
          description: Correlation ID for support.
    SchemeCode:
      type: string
      description: Payment scheme identifier.
      enum:
        - SCT
        - SCT_INST
        - SDD_CORE
        - SDD_B2B
        - OCT_INST
        - CBPRPLUS
        - CHAPS
        - T2
        - EURO1
        - FEDWIRE
        - OTHER
    SchemeVersion:
      type: string
      description: ISO 20022 scheme version / SR year.
      enum:
        - SR2025
        - SR2026
    Quality:
      type: string
      description: Postal database verification depth.
      enum:
        - premium
        - standard
        - basic
    TargetFormat:
      type: string
      description: >
        Target conversion format. `auto` lets ARS select the best achievable
        format.
      enum:
        - auto
        - FULLY_STRUCTURED
        - HYBRID
        - FULLY_UNSTRUCTURED
    Direction:
      type: string
      description: Payment processing direction. OUTBOUND = sending; INBOUND = receiving.
      enum:
        - OUTBOUND
        - INBOUND
    PartyRole:
      type: string
      description: >
        ISO 20022 party role. Determines the PostalAddress24 XSD variant:

        - **__2 variant** (ultimate_debtor, ultimate_creditor,
        initiating_party):
          TownName AND Country are MANDATORY. FULLY_UNSTRUCTURED is NEVER permitted (REG-05).
        - **__1 variant** (debtor, creditor):
          Max 3 AddressLines. FULLY_UNSTRUCTURED is permitted until SR2026 cutover (2026-11-22T02:30:00Z) for INBOUND;
          banned OUTBOUND post-cutover.
      enum:
        - debtor
        - creditor
        - ultimate_debtor
        - ultimate_creditor
        - initiating_party
    OutputMode:
      type: string
      description: |
        Address line rendering constraints applied during output formatting.
        - EPC: 2 lines × 70 chars
        - CBPR_PLUS: 3 lines × 35 chars
        - MT_LEGACY: 2 lines × 35 chars
        - COMPLIANCE: 7 lines × 70 chars
      enum:
        - EPC
        - CBPR_PLUS
        - MT_LEGACY
        - COMPLIANCE
    MessageType:
      type: string
      description: >
        ISO 20022 message type. R-transaction types (pain.002, pain.007,
        pacs.002,

        pacs.004, camt.029, camt.052, camt.053, camt.054, camt.055, camt.056,
        camt.058, camt.110, camt.111) must be submitted to R-transaction
        endpoints only

        (EP-07, EP-15). Submitting them to Check/Convert endpoints returns HTTP
        422 (REG-06).
      enum:
        - pain.001
        - pain.002
        - pain.007
        - pain.008
        - pacs.002
        - pacs.003
        - pacs.004
        - pacs.008
        - pacs.009
        - pacs.010
        - camt.029
        - camt.052
        - camt.053
        - camt.054
        - camt.055
        - camt.056
        - camt.057
        - camt.058
        - camt.060
        - camt.105
        - camt.106
        - camt.107
        - camt.108
        - camt.109
        - camt.110
        - camt.111
    AddressFormat:
      type: string
      description: Detected or target address format classification.
      enum:
        - FULLY_STRUCTURED
        - HYBRID
        - FULLY_UNSTRUCTURED
    ChannelType:
      type: string
      description: Payment delivery channel type.
      enum:
        - api
        - file
        - other
    AutoCorrectStatus:
      type: string
      description: Outcome of AutoCorrect processing for an address.
      enum:
        - VALIDATED
        - REPAIRED
        - PARTIALLY_REPAIRED
        - NOT_REPAIRED
    ReasonCode:
      type: object
      xml:
        name: ReasonCode
      description: >
        Structured reason code. Prefix indicates category:

        FMT = format, FLD = field, REG = regulatory, ENT = entity, VRF =
        verification, CNV = conversion.
      required:
        - code
        - severity
        - message
      properties:
        code:
          type: string
          description: Reason code in PREFIX-NN format (e.g. FMT-01, REG-05, VRF-03).
          example: REG-05
        severity:
          type: string
          enum:
            - ERROR
            - WARNING
            - INFO
          description: Severity level.
        field:
          type: string
          description: ISO 20022 field name the reason applies to (e.g. TownName,
            AddressLine).
        message:
          type: string
          description: Human-readable explanation.
        ruleSource:
          type: string
          description: Regulatory reference (e.g. EPC SCT Rulebook §3.4, CBPR+ MP §2.1).
  responses:
    BadRequest:
      description: Bad Request — malformed request body or invalid parameter.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: 400
            message: Request body is not valid JSON.
            requestId: b1a2c3d4-0000-0000-0000-000000000000
        application/xml:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example: |
            <?xml version="1.0" encoding="UTF-8"?>
            <ErrorResponse>
              <code>400</code>
              <message>Request body is not valid JSON.</message>
              <requestId>b1a2c3d4-0000-0000-0000-000000000000</requestId>
            </ErrorResponse>
    Unauthorized:
      description: Unauthorized — missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: 401
            message: Authentication credentials are missing or invalid.
            requestId: b1a2c3d4-0000-0000-0000-000000000001
        application/xml:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example: >
            <?xml version="1.0" encoding="UTF-8"?>

            <ErrorResponse>
              <code>401</code>
              <message>Authentication credentials are missing or invalid.</message>
              <requestId>b1a2c3d4-0000-0000-0000-000000000001</requestId>
            </ErrorResponse>
    UnprocessableEntity:
      description: Unprocessable Entity — semantic validation failure (e.g.
        R-transaction type submitted to a non-R endpoint).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: 422
            message: R-transaction message types (e.g. pacs.002) are not permitted on this
              endpoint. Use /r-transaction-message-party-addresses.
            requestId: b1a2c3d4-0000-0000-0000-000000000004
        application/xml:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example: >
            <?xml version="1.0" encoding="UTF-8"?>

            <ErrorResponse>
              <code>422</code>
              <message>R-transaction message types (e.g. pacs.002) are not permitted on this endpoint.</message>
              <requestId>b1a2c3d4-0000-0000-0000-000000000004</requestId>
            </ErrorResponse>
    TooManyRequests:
      description: Too Many Requests — rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: 429
            message: Rate limit exceeded. Retry after 10 seconds.
            requestId: b1a2c3d4-0000-0000-0000-000000000005
        application/xml:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example: |
            <?xml version="1.0" encoding="UTF-8"?>
            <ErrorResponse>
              <code>429</code>
              <message>Rate limit exceeded. Retry after 10 seconds.</message>
              <requestId>b1a2c3d4-0000-0000-0000-000000000005</requestId>
            </ErrorResponse>
    InternalServerError:
      description: Internal Server Error — unexpected server-side failure.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: 500
            message: An unexpected error occurred. Please contact support with your
              requestId.
            requestId: b1a2c3d4-0000-0000-0000-000000000006
        application/xml:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example: |
            <?xml version="1.0" encoding="UTF-8"?>
            <ErrorResponse>
              <code>500</code>
              <message>An unexpected error occurred.</message>
              <requestId>b1a2c3d4-0000-0000-0000-000000000006</requestId>
            </ErrorResponse>
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your ioNova platform API key. Generate it from your organisation
        admin in the ioNova app, then paste it here to test.
```