Add optional TenureInfo qualifiers for contract-line context

[Cyndi-E]

What this PR does / why we need it:

This PR addresses the discussion in Issue #67 by proposing optional response qualifiers to TenureInfo for review, to provide additional context for interpreting the existing tenure result in shared, multi-line, family, or business contract structures.

The change introduces two optional attributes:

• contractLineStructure: indicates whether the CSP can determine that the underlying contract contains a single line or multiple lines.
• lineToContractHolderAssociation: indicates whether the CSP can determine the association between the queried line and the contract holder.

The proposal separates contract-line structure from line-to-contract-holder association to avoid mixing two different semantics in a single field.

Both attributes are optional and may be omitted if the relevant information or relationship is not available, ambiguous, unreliable, or not permitted to be shared.

This PR does not broaden the KYC Tenure API into a general customer-profile or account-information interface. The added fields are intended only as lightweight qualifiers of the existing tenure signal and do not define a universal or fixed mapping to trust level.

Which issue(s) this PR fixes:

Related to #67.

Changelog input

Added optional `contractLineStructure` and `lineToContractHolderAssociation` qualifiers to `TenureInfo` to provide additional context for interpreting tenure results in shared or multi-line contract structures.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: Cyndi-E / name: Cyndi Lin (5bb0143)

[shilpa-padgaonkar]

/LGTM

[HuubAppelboom]

These proposed changes go against one of the primary goal of the CAMARA project, to provide open, global, and interoperable API solutions. In Europe, these extra data points cause the API to be subject to user consent, which makes this API useless for fraud detection and prevention. We propose to make these data points part of a seperate API, for which user consent is required, so it can be used globally.

[HuubAppelboom]

Hi @KeldaAnders @shilpa-padgaonkar @Cyndi-E @albertoramosmonagas @GillesInnov35

Apart from the discussion whether this should be implented in a separate API, I think the terminology used should be the same as elsewhere in CAMARA, and should follow as much as possible the glossaries defined in Commonalties and in ICM.

For example, the term "line" is very ambiguous, especially when considering this API can also be used by fixed line telephony and/or internet providers. For example a business can be on a single fixed telephony line (but with thousands of phone extensions). Depending on what use case you are looking for, it may be better to describe this as single phone number or multiple phone numbers, or as single subscription vs multiple subscriptions.

Another example is contract holder, I believe else where and in the Glossary the term subscriber is defined.

The other point is that it must be clearly defined which case is a "multi"-subscription (or line).
For example:

• a subscriber (and single end-user) has a mobile subscription and a iWatch with an eSIM in it. Both are associated with a single phone number. Is this now a multi-line ?
• a subscriber has a mobile subscription in use with a handset, and a data-only subscription with an iPad. You don't know whether this is the same end user, but it could be that it is two end users (and the one using the data-only sub has also a sub with another telco). Is this now multi-line ?
• If a subscriber has a fixed internet line with telephony and a mobile subscription, does this also qualify as a multi-line ??
• If a telco has multiple brands, and subscriber has a subscription with brand A and a brand B, should ths count as a multi-line ?
• If a mobile subscription is an enterprise subscription, should it always be counted as multi-sub ? Even when you know that end user is in a single person house hold ?

Clearly a better definition is required what "multi" stands for, but that also depends what the information is used for.

If the information is just to enlighten what the Tenure API returns (it is currently defined as relating to a phone number), it may be simpler to keep the definition of single/multi also related to phone numbers (whether the subscriber has multiple phone numbers in his contract). And yes, fixed phone numbers should be included then.

And if there will be an API that relates to how long a subscription is in use with the subscriber, then it should reflect the number of subcriptions the subscriber has.

[Cyndi-E]

Hi @KeldaAnders @shilpa-padgaonkar @Cyndi-E @albertoramosmonagas @GillesInnov35

Apart from the discussion whether this should be implented in a separate API, I think the terminology used should be the same as elsewhere in CAMARA, and should follow as much as possible the glossaries defined in Commonalties and in ICM.

Thanks @HuubAppelboom for highlighting these points. I agree that line and multi-line would benefit from a more precise and glossary-aligned definition, and that the intended counting unit and grouping boundary may warrant further clarification, including whether the counting unit is based on phone numbers or subscriptions.

Since this depends on the underlying use case and CSP-supported semantics, I have continued the clarification in [this comment in #67]. Based on the outcome, the terminology and definition in PR #85 can be updated accordingly.

I have also checked the ICM glossary. It defines Subscriber as the mobile subscriber of the Operator and notes that the Subscriber is usually, but not always, the End-User. This is related to the intended contract holder concept, but the glossary does not explicitly define the two as equivalent. In addition, the current Tenure API already uses subscriber for the subject of the queried network subscription, so a direct replacement of contract holder with subscriber could make the qualifier ambiguous.

It may therefore be appropriate to retain contract holder for this qualifier, with a small wording refinement in the field description for clarity.

[HuubAppelboom]

@Cyndi-E The same discussion around subcriber vs contract holder plays with other KYC APIs, like Age Verification, KYC Match etc. With Age Verification it is called the contract owner. What may be better is to have this defined in the Glossary at Commonalities, so that we have a common definition for this, that should be used with all APIs.

[albertoramosmonagas]

Thanks @Cyndi-E, @HuubAppelboom and @KeldaAnders. The direction is reasonable — so I will keep this short and focus on the points I think need to be resolved:

1. Terminology is not yet interoperable — this is the main blocker. "line" and "contract holder" carry different meanings across mobile, fixed, eSIM/multi-device, and enterprise cases, and our KYC family is inconsistent (Age Verification uses "contract owner"; ICM defines "subscriber" without equating it to the holder). I do not think we should settle a local definition here. Huub's suggestion to define these terms once in Commonalities and reuse them across Tenure, Age Verification and KYC Match is the right path, and I would gate the merge on that alignment.

2. "Multi" has no normative counting unit. As written, MULTI_LINE_CONTRACT will mean different things at different operators, which defeats the point of standardising it. Before merge we need to pin down, in the field description, whether the counting unit is phone numbers or subscriptions, and how the edge cases Huub raised are handled (eSIM companion device, data-only tablet, fixed+mobile bundle, multi-brand under one operator). Without this, consumers cannot compare the value across CSPs.

3. Purpose limitation needs an explicit answer. Holder-association and household/contract structure are attractive well beyond fraud prevention (e.g. identifying the buyer/decision-maker in a household for campaign targeting), which is Huub's point. Tenure's authorised purpose is identity and fraud prevention; the guardrail text helps but does not close this. From our side these new fields would need a fresh per-market privacy assessment before they could be relied upon — I would not assume the current Tenure legal basis extends to them.

Two things that should be settled but need not block this PR:

• Overlap with KYC Match. Cyndi's CSP-determined-qualifier vs. consumer-derived-match distinction is reasonable; I would just like the group to confirm that boundary in the notes so we do not create two overlapping ways to answer the same question.
• serviceActivationDate (@KeldaAnders). Please track it as its own issue rather than folding it into this PR — it is a larger change, partly overlaps Tenure's core signal, and (per Huub) SIM-swap vs. burner-SIM timing profiles likely need their own discussion and privacy assessment.

[HuubAppelboom]

I have also checked the ICM glossary. It defines Subscriber as the mobile subscriber of the Operator and notes that the Subscriber is usually, but not always, the End-User. This is related to the intended contract holder concept, but the glossary does not explicitly define the two as equivalent. In addition, the current Tenure API already uses subscriber for the subject of the queried network subscription, so a direct replacement of contract holder with subscriber could make the qualifier ambiguous.

It may therefore be appropriate to retain contract holder for this qualifier, with a small wording refinement in the field description for clarity.

@Cyndi-E I think in CAMARA terms the subscriber is per definition always the contract holder, so why introduce a new definition ?