[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

[HuubAppelboom]

@GillesInnov35 @ToshiWakayama-KDDI @PaoloCommissari One thing that needs consideration with multiple addresses is that you may not want to expose too much information. With KYC Match the intention is that you just verify the data that has been submitted. In case the API Consumer has no information for example on the DOMICILE address, but does have a CONTACT address, they may try to submite all possible combinations (with as a data the CONTACT address), to find out whether the CONTACT address is also the DOMICILE address etc.

So what about the following proposal:

For Match and the case the API Consumer wants to check a specific address, they indicate this through an identifier which type of address needs to be checked. In case no identifier is used, and the API Providers has multiple adresses, you simply return the match result for the best possible match (without indicating what address type it is).

For other case like KYC Fill-in, you may want to have in the scope defined (optionally) what type of address is required; in case there is no type defined, you just reply with the current standard address; in case the requested specific address type is not available, you answer with not_available.

[ToshiWakayama-KDDI]

Thanks @HuubAppelboom . Makes much sense to me. Let me take some time to check with my KYC product team, as Japan is now in holiday week...

[PaoloCommissari]

@GillesInnov35 @ToshiWakayama-KDDI @PaoloCommissari One thing that needs consideration with multiple addresses is that you may not want to expose too much information. With KYC Match the intention is that you just verify the data that has been submitted. In case the API Consumer has no information for example on the DOMICILE address, but does have a CONTACT address, they may try to submite all possible combinations (with as a data the CONTACT address), to find out whether the CONTACT address is also the DOMICILE address etc.

So what about the following proposal:

For Match and the case the API Consumer wants to check a specific address, they indicate this through an identifier which type of address needs to be checked. In case no identifier is used, and the API Providers has multiple adresses, you simply return the match result for the best possible match (without indicating what address type it is).

For other case like KYC Fill-in, you may want to have in the scope defined (optionally) what type of address is required; in case there is no type defined, you just reply with the current standard address; in case the requested specific address type is not available, you answer with not_available.

Hi @HuubAppelboom

It seems in line with what I had proposed above (#42), doesn't it?
Let me repeat myself:

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.

[GillesInnov35]

hi @HuubAppelboom , @PaoloCommissari, it suits me good, thanks a lot. As I said I think we should keep a simple parameter for address and add an addressType as you propose to target the comparaison. Concerning the response body we should not add much fields. Perhaps something like that could be proposed:

{
  "address": "45, blue street",
  "addressType": "DOMICILE"
  "......."
}

{
  "addressMatchResult": true,
  "addressTypeMatchResult": "CONTACT"
  "......."
}

WDYT?
Gilles

[HuubAppelboom]

@GillesInnov35 I would keep the result for the address as is, so without the "Result"at the end.

So like this:

{
"address": "45, blue street",
"addressType": "DOMICILE"
"......."
}
{
"addressMatch": true,
"addressTypeMatch": "CONTACT"
"......."
}

And to avoid any privacy discussions, only give the addressTypeMatch back in case the addressMatch is true (or has a very high matchScore).

With this you can be flexible enough:

• provide postive feedback on a certain address type when it matches also the adress
• provide also positive feedback when there is a matching address with a different address type
• provide negative feedback when these is no address matching whatsover (in this case answer with "addressTypeMatch": false)

[GillesInnov35]

yes @HuubAppelboom , you're right. I made a mistake by adding Result.

[ToshiWakayama-KDDI]

To be transferred to the new kyc-match repository, as agreed in 2025-09-30 meeting.

[ToshiWakayama-KDDI]

Hi @PaoloCommissari , @HuubAppelboom , @GillesInnov35 , all,

Do we still need to keep this Issue open?

Thanks,
Toshi

[GillesInnov35]

hi @ToshiWakayama-KDDI, after an internal discussion, we wonder if we should not question the validity of this information returned regarding Data Minimization principles (GDPR requirements) ?
The API will not return a match result but an information on contract. WDYT ?

[HuubAppelboom]

@ToshiWakayama-KDDI @GillesInnov35 @PaoloCommissari If privacy is a concern, mayeb we should only return the address match results for the when the addressType matches. Otherwise you may be sharing accidentally information that is not supposed to be shared, not? But what do you do then when the API Provider does not support this kind of classification ?

[GillesInnov35]

@HuubAppelboom , I agree with you. Indeed, there could be an issue in this scenario. This might mean that it is not interesting to include this property and to let the API provider apply its own rules by comparing with all known addresses or by limiting the scope to some of them.

[GillesInnov35]

@ToshiWakayama-KDDI , @HuubAppelboom , @PaoloCommissari as this interesting discussion is still in progress I propose to convert this issue to a discussion. WDYT ?

[HuubAppelboom]

@PaoloCommissari @GillesInnov35

In case there is still a good use case for it, I would propose to make this an optional field addressType.
When the Api Consumer sends with his request the addressType DOMICILE, only the DOMICILE address gets checked by the API Provider.

If the API Provider does not have the information (what address type it is), they can return unavailable for addressType (and still verify all the address fields).

When addressType is available, only that specific address will be checked.

And if you want to have multiple address types checked, simply run the API multiple time.

WDYT?