[kyc-match - address] no clear reference about what kind of address should be checked

[GillesInnov35]

Problem description
There isn't any clear reference in the specifications about what kind of address should be checked on operator side
Should we require Home, address, Postal or Installation address ?

• If not we let the operator define on which of these it'll base the check.
• We also know that it depends mostly on the back end solution called by the API.

Possible evolution
indicate clearly in API specifications what kind of address is required according to what information the user should be able to input.

BR
Gilles

[KevScarr]

Sharing Info: For contract customer (PAYM) we typically have multiple addresses on the account, billing and shipping can be different. For casual (PAYG) customers its likely to be one address.
We prioritize billing address over shipping address when we perform our checks today.

[HuubAppelboom]

We have two addresses, a contact address which is used for all official communication with the contract owner, and a billing address.

We typically use the contact address with Match, because that is usually where the contract owner resides, sim cards and handsets are beings shipped to etc.
A separate billing address is often used when you want a paper bill to be send to your bookkeeper. There are not many that have this as a separate address, but it does happen.

[HuubAppelboom]

As a suggestion, what may be a good idea is to verify an address against all possible adresses the Operator holds (and return the results of the best matching address). That way it doesn't really matter what use case it is etc.

[GillesInnov35]

At Orange, we use the contact address for the Match service. As proposed by Huub I think we could specify to check all addresses held by the MNO.
BR
Gilles

[PaoloCommissari]

Hi everyone,

Jumping in from TIM (Italy) to contribute to this interesting discussion.

In Italy — and generally in countries with civil law systems — individuals may legally declare multiple types of addresses with specific meanings and legal implications. For instance, we often manage:

• Residence (place of official legal residence)
• Domicile (designated legal address for service or communication)
• Temporary residence (current place of stay)
• Alongside more common types like contact and billing addresses

These distinctions are relevant not only for legal compliance, but also for identity verification, fraud prevention, and regulatory reporting.

What do you think of a model like this?

A flexible structure that allows (but doesn't require) address classification, while supporting simpler use cases (like only CONTACT and BILLING) for those who don't need legal granularity.

addresses:
  type: array
  items:
    type: object
    required: [streetName, streetNumber, locality, postalCode, country]
    properties:
      addressType:
        type: string
        enum: [RESIDENCE, DOMICILE, TEMPORARY_RESIDENCE, CONTACT, BILLING, SHIPPING, REGISTERED, OTHER]
        description: Optional. Legal or functional classification of the address.
      streetName:
        type: string
      streetNumber:
        type: string
      houseNumberExtension:
        type: string
      locality:
        type: string
      region:
        type: string
      postalCode:
        type: string
      country:
        type: string
        description: ISO 3166-1 alpha-2 code

Example

"addresses": [
  {
    "addressType": "RESIDENCE",
    "streetName": "Via Roma",
    "streetNumber": "12",
    "houseNumberExtension": "B",
    "locality": "Torino",
    "region": "Piemonte",
    "postalCode": "10121",
    "country": "IT"
  },
  {
    "addressType": "DOMICILE",
    "streetName": "Corso Buenos Aires",
    "streetNumber": "45",
    "locality": "Milano",
    "region": "Lombardia",
    "postalCode": "20124",
    "country": "IT"
  },
  {
    "addressType": "BILLING",
    "streetName": "Via della Conciliazione",
    "streetNumber": "4",
    "locality": "Roma",
    "region": "Lazio",
    "postalCode": "00193",
    "country": "IT"
  }
]

This would allow each operator to decide how much they want to use addressType:

• Some (like HuubAppelboom - KPN) could keep it simple and use just one or two addresses.
• Others (like TIM) could leverage the legal granularity when required by regulation or business logic.

We’re happy to refine this together with the community!

Thanks

P.

[HuubAppelboom]

@PaoloCommissari For the Netherlands, we also have the houseNumberExtension.
We are also in the process of discussing the minimum supported address attributes (in the Netherlands, postalcode + streetnumber + houseNumberExtension is sufficient to define an address exactly); it may be better to keep things optional, in stead of everything as required.
Please note that there is also an "address" defined as a complete address string in the current specs.

[HuubAppelboom]

PS. One issue is what do you answer with KYC Match when the API Consumer submits for example a DOMICILE address, but the API Provider only has a CONTACT address ?

[PaoloCommissari]

Hi @HuubAppelboom ,

On minimal address fields & houseNumberExtension

Totally agree. In Italy we also make use of houseNumberExtension, especially in urban contexts. The Dutch convention of using just postalCode + streetNumber + houseNumberExtension as a minimal identifier makes perfect sense — and reinforces the idea that the model should be flexible and accommodate national differences.

That’s why in our updated proposal we removed the required block altogether and suggest implementers define their own minimal set, based on local regulatory needs. We also added support for a fullAddress field as a fallback or for legacy use cases where structured parsing isn't feasible.

Here’s the revised model we're proposing:

addresses:
  type: array
  items:
    type: object
    properties:
      addressType:
        type: string
        description: >
          Optional. Legal or functional classification of the address.
          Suggested values: RESIDENCE, DOMICILE, TEMPORARY_RESIDENCE, CONTACT, BILLING,
          SHIPPING, REGISTERED, OTHER. Not restricted to this list.
      streetName:
        type: string
      streetNumber:
        type: string
      houseNumberExtension:
        type: string
      locality:
        type: string
      region:
        type: string
      postalCode:
        type: string
      country:
        type: string
        description: ISO 3166-1 alpha-2 code
      fullAddress:
        type: string
        description: Optional. Unstructured full address as a fallback or legacy format.

This allows both granular implementations and simpler ones to coexist.

On KYC Match and mismatched address types

In terms of matching logic: we propose keeping things as simple and practical as possible.

The API consumer sends an address (with or without addressType), and the provider scans its stored addresses to find a match. If a match is found — even if the address type differs — the provider can respond with:

{
  "match": true,
  "matchedAddressType": "CONTACT"
}

Optionally, if the consumer provided a specific addressType, the provider may include that as requestedAddressType:

{
  "match": true,
  "requestedAddressType": "DOMICILE",
  "matchedAddressType": "CONTACT"
}

This gives the consumer full context without requiring complex negotiation or introducing false negatives when the address itself is valid but classified differently.

Let us know what you think

Thanks again,

P.

[HuubAppelboom]

@PaoloCommissari Hi, it sounds ok to me.
Regards
Huub

[GillesInnov35]

hi @HuubAppelboom , @PaoloCommissari , I agree that adding address type could be useful to target which iformation should be match and perhaps which referential must be requested. But I'm not fully convinced that we should add an array to the request body.
The design you proposed is an address entity description with multiple possible address for a client/contract. I'm not sure that multiple address will have to be matched during the user journey, Most of the cases only 1 address will be input, won't it ? I think that break of backward compatibility is decided if evolutions are strongly needed, WDYT ?
Gilles

[PaoloCommissari]

Hi @GillesInnov35 ,

Thanks for your thoughtful feedback, I totally see your point.

You're right that in most real-world user journeys, the API consumer will typically submit only one address. Our proposal to use an array structure wasn’t meant to mandate multiple addresses, but rather to:

• Support use cases where multiple addresses are declared (e.g. during onboarding or KYC updates);
• Allow reuse of the same structure on the provider side, where customers often have more than one address stored;
• Avoid future-breaking changes by making the model extensible from the start — especially to support international legal requirements (e.g. domicile, residence, etc.)

In practice, the request would still carry just one address in most cases — the array simply provides flexibility when needed.

On backward compatibility: it's worth mentioning that the KYC API is currently in Updated Initial status in the CAMARA lifecycle — not yet in Stable. That means we’re still in the phase where “bold” improvements can and should be made, especially if they bring structural clarity and support a broader range of implementations across jurisdictions.

That said, we can definitely consider a balanced path forward:

1. Maintain the existing single-address structure as default;
2. Introduce addressType as an optional property;
3. Optionally support an address array for future-proofing, to handle complex or multi-address contexts.

This approach keeps things simple and backward-compatible for most implementers, while opening the door to richer models where needed.

Thanks,

P.

[ToshiWakayama-KDDI]

Hi @PaoloCommissari , @HuubAppelboom , @GillesInnov35 ,

Sorry for the slow comments. I have paid attention to Discussion #193 only on this subject, but now I know.

For KDDI, I have the similar thought with Huub KPN and Gilles Orange.

From PaoloCommissari's comment ( #42 )

This would allow each operator to decide how much they want to use addressType:

• Some (like HuubAppelboom - KPN) could keep it simple and use just one or two addresses.

From Gilles's comment ( #42 )

hi @HuubAppelboom , @PaoloCommissari , I agree that adding address type could be useful to target which iformation should be match and perhaps which referential must be requested. But I'm not fully convinced that we should add an array to the request body.
The design you proposed is an address entity description with multiple possible address for a client/contract. I'm not sure that multiple address will have to be matched during the user journey, Most of the cases only 1 address will be input, won't it ? I think that break of backward compatibility is decided if evolutions are strongly needed, WDYT ?
Gilles

Array is a good idea to handle multiple-addresses, but KYC Match and Fill-in APIS have been designed as they are simple and easy to use, so the attributes are listed in an one-dimension way. One of my concerns is that using array would make them complex.

In addition to that, using array may cause backward compatibility problem, which is very important as KYC Match API has been provided commercially.

Another concern I have is about multiple-address support. I understand that address-related information we Operators should provide to API consumers should be information certified with some identification of our subscribers. So, one certified/identified address may be enough. In Italy, it seems there are multiple addresses an operator has, but can all addresses be certified/identified by some id documents or something?

One suggestion from me would be that, if multiple address is needed for Italy or some other countries, it would be better to add an extension array attribute, e.g. extendedAddresses, as some region optional parameters. For KYC Match, all attributes are optional, so, no backward compatibility problem will not happen by adding an array attribute.

Just an image of the suggested API spec:

(we have existing attributes)

phoneNumber:
idDocument:
name:
givenName:
familyName:
nameKanaHankaku:
nameKanaZenkaku:
middleNames:
familyNameAtBirth:
address:
streetName:
streetNumber:
postalCode:
region:
locality:
country:
houseNumberExtension:
birthdate:
email:
gender:

(to add regional extended attributes)

Regional attribute extension:

extendedAddresses:
type: array
items:
addressType:
streetName:
streetNumber:
houseNumberExtension:
locality:
etc.

Sorry for the long comment, but WDYT?

BR.
Toshi

[ToshiWakayama-KDDI]

Hi @PaoloCommissari ,

Apart from Array/multiple-address, I have another comment. As Huub commented (#42 ), KYC Match / Fill-in APIs have the 'address' attribute which is used for a complete address string, as Japan and some other countries do not use pieces like streetName and streetNumber. Please do not forget such an aspect for our global APIs. (Thanks, Huub.)

BR,
Toshi

[GillesInnov35]

Thanks @ToshiWakayama-KDDI , @PaoloCommissari , I'm not sure that adding complexity to the API design will be so helpful for proof of identity. The purpose of the API is not tho describe an individual (as for example TMF Party/individual makes it) but to provide some information to quickly give a signal.
BR
Gilles