Optional standardized operator-defined recency bucket to be returned with swapped boolean(SimSwap)

[KeldaAnders]

Problem description
Consumers have requested coarse time-band signals to support better fraud and risk decisioning. The current /check endpoint returns only a Boolean (swapped), which by itself is an insufficient signal.

---

Possible evolution

Return an Optional standardized operator-defined recency bucket.

Proposed approach:

• Keep the existing Boolean swapped field.
• Add an optional simSwapAgeBandEnum.
• Preserve backward compatibility.

This keeps /check aligned with its purpose as a simple threshold signal while optionally exposing standardized context.

The consuming party (e.g., a bank) can then apply its own thresholds, ML features, or step-up logic outside the API contract.

---

Proposed request/response pattern

Request

{
  "phoneNumber": "+1234567890"
}

The request remains intentionally minimal and consumer-agnostic.

---

---

Response

{
  "swapped": true,
  "simSwapAgeBandEnum": 1,
}

• swapped remains the primary contract
• enum fields provide optional additional signal

---

YAML schema note

Suggested explanatory note:

simSwapAgeBandEnum is an optional standardized recency bucket representing the elapsed time between the SIM activation/change date and the current time.
The value maps the duration into fixed bands (0–14), ranging from 0 hours up to 3+ years.

Special values:

• 111 → Change has not occurred
• 999 → Subscriber valid but no real-time profile available

---

Standardized AgeBandEnum mapping

0  = 0h ≤ d < 4h
1  = 4h ≤ d < 12h
2  = 12h ≤ d < 1d
3  = 1d ≤ d < 2d
4  = 2d ≤ d < 5d
5  = 5d ≤ d < 7d
6  = 7d ≤ d < 14d
7  = 14d ≤ d < 30d
8  = 30d ≤ d < 60d
9  = 60d ≤ d < 90d
10 = 90d ≤ d < 180d
11 = 180d ≤ d < 1y
12 = 1y ≤ d < 2y
13 = 2y ≤ d < 3y
14 = 3y+

111 = Change has not happened
999 = Subscriber valid, but no real-time profile found

enum: [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,111,999]

Backward compatibility

This proposal introduces additive-only changes:

• Existing swapped behavior remains unchanged
• New optional response fields:
  • simSwapAgeBandEnum

Existing clients remain unaffected.

---

The goal is to keep the API focused on known business value & delivering simple operator signals, while leaving policy and decisioning to consuming systems.

[KeldaAnders]

@albertoramosmonagas In response to #248 (comment)

We believe the standardized operator-defined age-band enrichment should remain an optional additive field in the existing /check response, rather than introducing a new endpoint.

We have received direct business and consumer use-case requests for this type of recency signal to support fraud detection and risk decisioning. The enrichment remains directly related to the check itself: it preserves the existing swapped boolean as the primary contract while optionally providing additional operator context in the same call. Requiring a separate endpoint for closely related information adds unnecessary complexity, whereas optional fields allow operators who wish to provide the signal to do so, while others can simply omit it.

To keep the discussion focused, we suggest separating this enrichment proposal from the #248 (comment)
discussion, #253 can be a dedicated issue to continue the conversation.

Position summary

• ❌ No consumer-defined vectors in /check
• ✅ Optional standardized operator-defined age-band enrichment
• 🔒 swapped remains the core response contract
• ➕ Enrichment is additive and optional for operators

cc @maheshc01 @yyeAduna @gmuratk

[shilpa-padgaonkar]

cc @AxelNennker

[albertoramosmonagas]

Hi @KeldaAnders, thanks for open a new discussion and for the clarification.

From Telefónica’s side, I still do not support adding an optional recency-band field into /check. The core reason is not whether the field is optional or additive at payload level. The core reason is that the current API already separates two different questions in both the specification and the product requirements:

• /check for answers whether a SIM swap happened within a past period defined by maxAge
• and /retrieve-date for answers when the last SIM swap happened

This separation is explicit in the current API documentation and data model. /check is defined as a threshold-based boolean response, while time-related information is handled through retrieve-date. That is why I do not think “same call convenience” is enough justification to merge both concerns into the /check contract. A separate endpoint for time-related information is not hypothetical complexity here; it already exists in the API.

I also see a modelling problem in the proposed enum. It does not only represent recency bands, but also mixes in other meanings such as “no change has occurred” or “profile not available”. That combines different dimensions into a single signal, whereas the current API keeps those concerns separated. So the concern remains the same: even if the field is optional, this would move /check away from a simple threshold result and toward a discretized time-signal interface, which overlaps with the role already covered by retrieve-date.

For that reason, my position remains no consumer-defined vectors in /check, and no operator-defined recency-band enrichment inside /check If there is interest in standardizing a coarse recency signal beyond the current boolean, that should be discussed as a separate capability proposal, not as an enrichment of the current /check response, but open to hearing the perspectives of other API maintainers

[AxelNennker]

I think there is a business need to improve "/check". Also, /check is more privacy friendly than /retrieve-date and some legislations might allow /check but not /retrieve-data or allow it to more API consumers.

I could also imagine that /retrieve-date becomes more privacy friendly by not returning a data that is exact to the milli-second, but that is not this issue.

Regarding backward compability, I am not sure how relavant that is regarding MNO's who do not want to advance or API consumers who might need to ignore a field they do not understand or expect.
There is also the aspect of interoperability, if only a percentage of MNOs implement the change.

I prefer this approach to the API consumer having more control over input parameters.

From a "mathematical" POV, I would define this differently. I would move all interval one index up and would not use 111 and 999.

-1 = Subscriber valid, but no real-time profile found
0 = Change has not happened
1 = 0h ≤ d < 4h
2 = 4h ≤ d < 12h
3 = 12h ≤ d < 1d
4 = 1d ≤ d < 2d
5 = 2d ≤ d < 5d
6 = 5d ≤ d < 7d
7 = 7d ≤ d < 14d
8 = 14d ≤ d < 30d
9 = 30d ≤ d < 60d
10 = 60d ≤ d < 90d
11 = 90d ≤ d < 180d
12 = 180d ≤ d < 1y
13 = 1y ≤ d < 2y
14 = 2y ≤ d < 3y
15 = 3y+

That leaves room enum = ⌊d⌋+12 if somebody want that or somehting logarithmic... ;-)
Where do the 3+ come from? Customer demand?

[KeldaAnders]

Thanks @albertoramosmonagas and @AxelNennker for the thoughtful feedback — I appreciate both your perspectives.

Before getting into implementation details, I want to emphasize the primary driver for this proposal. Based on repeated discussions with aggregators, banks, and fintech customers using this data, there is consistent and overwhelming feedback that the current boolean signal in /check is not granular enough for real fraud decisioning workflows. What these systems need is not the exact timestamp, but coarse recency bands that allow them to differentiate risk levels (minutes vs hours vs days).

Today, consumers often approximate this by issuing multiple /check requests with different maxAge values, which increases API calls and operational complexity. The intent of the proposal is to provide a standardized coarse recency signal so consumers can obtain that information in a single request while preserving the existing boolean result.

---

@albertoramosmonagas I understand the concern about maintaining the conceptual separation in the current API design:

• /check → threshold-based answer (“did a swap happen within X?”)
• /retrieve-date → exact timestamp of the last SIM swap

That separation is clearly reflected in the current specification. The proposal does not aim to replace /retrieve-date, which remains the appropriate endpoint when an exact timestamp is required. Instead, the proposal focuses on bridging the gap between a binary signal and a precise timestamp by introducing a coarse recency indicator.

---

@AxelNennker I like the direction of simplifying the enum and separating state from recency, particularly:

-1 = Subscriber valid, but no real-time profile found
0  = Change has not happened

---

That structure keeps availability states distinct from time intervals, which makes the signal easier to interpret.

Your proposed interval structure also makes sense conceptually. The earlier inclusion of the 3y+ band was mainly intended to keep the signal open-ended, since some customers have asked for the ability to understand whether a SIM has changed far beyond shorter operational windows. That said, the exact bands should ultimately reflect real customer demand and practical risk scoring needs, and can certainly be refined with input from the group.

Happy to continue iterating on the modelling details. The main goal is to ensure the API supports real-world fraud prevention use cases while preserving interoperability and clarity in the specification.

[albertoramosmonagas]

Hi @AxelNennker & @KeldaAnders,

I understand that there may be a real business need for an intermediate signal between a pure boolean and an exact timestamp. I also understand the argument that, in some regulatory or privacy contexts, /check may be easier to deploy than /retrieve-date, and that some consumers may currently be addressing this need by making multiple /check calls with different maxAge values. That said, from Telefónica’s perspective, we still believe this does not mean that the right solution is to enrich the current /check response. The main reason is that the current API already explicitly separates two different questions through /check and /retrieve-date.

For that reason, the fact that some consumers want an “intermediate” signal can be interpreted as evidence of an additional capability need, but not necessarily as evidence that /check should evolve into a recency-signal interface.

On the privacy point, I agree that /check may be a more privacy-friendly operation in some markets. But the API already models that asymmetry in a clean way:

• /retrieve-date covers scenarios where the date cannot be exposed.
• /check already limits the query through maxAge, including the thresholds applicable under operator policy or local regulation.

In other words, the privacy argument helps explain why both endpoints exist, but in our view it does not justify merging their roles.

I also agree that, if this discussion continues, it would make sense to keep state/availability and recency as separate dimensions. But for me that is a secondary modelling question. The primary question, before discussing enums or specific bands, is whether this type of signal should belong to the current /check contract at all.

If there is interest in standardizing a coarse recency signal, we believe that should be discussed as a separate capability, rather than as an extension of the current /check contract.

[bigludo7]

I have an issue with the proposition related to privacy/RGPD/DPO

We understand that banks want only an API using Legitimate Interest legal base (probably @KeldaAnders you can confirm as you speak with them- I have confirmation from French market).
I should said to be more straightforward: our customer ask: "This sim-swap check must be silent from user perspective" (same @KeldaAnders please provide your view).

The retrieve-date is an absolute no go in some of our geographies in legitimate interest. Only explicit consent is acceptable from our legal but no business on it with explicit consent. Zero revenue.

The check is sometime tough to sell to DPO in Legitimate interest depending on the search depth- in France our DPO request to limit the depth to 7 days in the past ! we will have probably some 'interesting' discussion in future in Poland.

So I assume that adding this information will be headache from a DPO perspective - indeed we break the simplicity to legally assess the check as doing some part of retrieve-date will be added. I'm afraid that some operator will require explicit consent while other will not send back this new information.

I assume your requirement is fair @KeldaAnders and open to improve but in this case why not having a new endpoint in the API? Do you interlocutors will be committed to buy if an explicit consent is required?

[shilpa-padgaonkar]

@bigludo7 : We also do not offer retrieve-date endpoint.

We have same feedback from customers where they expect no user interaction. We also have another feedback where customers did not wish to have several endpoints to orchestrate against for this data.

Having said that, having separate endpoint for the enumeration is not a show stopper for us (just as fyi its also falls under legitimate interest). But our experience is that, once this response with enumeration is made available, just a boolean check response was not of much value to most customers.

[bigludo7]

Hi @shilpa-padgaonkar
Yes got your point...adding a third endpoint will add more fragmentation and perhaps no the right idea.

Another suggestion thinking loudly... What about providing this threshold in the retrieve-date as an alternative to the date - the API could send one or the other? as it reduces the data provided it may work in some country in Legitimate Interest where retrieve-date with real date don't?

I have a preference to not touch check to avoid RGPD issue....

[shilpa-padgaonkar]

@bigludo7 retrieve-date would be ok but we would need to make the latestSimChange response optional and allow enumerated response as we wont support providing precise timestamp.

[KeldaAnders]

On retrieve-date, I agree with @bigludo7 & @shilpa-padgaonkar

• age-band ≠ timestamp
• it is a coarse classification, not historical data
• it can be introduced in a privacy-preserving way without the same regulatory impact as returning latestSimChange

: it can work if adapted:

• make latestSimChange optional
• allow an optional age-band (enum) response by default
• avoid precise timestamps in Legitimate Interest contexts

This preserves the endpoint while meeting data minimization requirements.

[AxelNennker]

To avoid a breaking change I suggest keeping lastestSimChange but the API provider would return a value that is in the middle of the "enum".