feat: add /retrieve-age-band (SIM swap age band) endpoint

[KeldaAnders]

Title: feat: add /retrieve-age-band (SIM swap age band) endpoint

Adds a standalone, single-purpose operation that returns a standardized SIM swap recency band (simSwapAgeBand) only. Supersedes #266 (which was opened from main by mistake) and incorporates that PR's review feedback. Targeting release 2.1.0.

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Adds POST /retrieve-age-band to the SIM Swap API: an alternative way to expose SIM swap recency for providers that do not expose the exact SIM swap date. It returns a time-bucketed value indicating how recently a SIM swap/activation occurred — and nothing else.

• Purely additive. /check and /retrieve-date (and their schemas, request bodies, and examples) are preserved unchanged. The only additions are the new path, the SimSwapAgeBand / SimSwapAgeBandInfo / CreateSimSwapAgeBand schemas, the AGEBAND_* examples, the new scope, and the related description updates.
• Single-purpose by design. The response carries the band value only. It does not include the swapped Boolean (/check) or the SIM change timestamp (/retrieve-date).
• Alternative, not mandatory. Providers are not expected to support this in addition to check/retrieve-date; support depends on the provider's capabilities and commercial use case.
• Band values: 1–15 represent increasing recency bands (4h → 3y+); 999 indicates no SIM swap event was found. When the information is unavailable for the subscriber, the request returns 422 SERVICE_NOT_APPLICABLE.
• New scope sim-swap:retrieve-age-band, alongside sim-swap:check, sim-swap:retrieve-date, and the API-level sim-swap scope.

Adding a new endpoint is backward-compatible, so this targets a MINOR bump to 2.1.0 (URL path unchanged: /sim-swap/v2).

Which issue(s) this PR fixes:

Fixes #260
Fixes #253

Changes after the #266 review

• Renamed the field from simSwapAgeBandEnum to simSwapAgeBand (the schema already defines it as an enum). — per @jpengar
• Moved the "no real-time profile" case out of the success enum. -1 is removed; unavailable information is now an error (422 SERVICE_NOT_APPLICABLE) rather than mixing time-bucket and error semantics. — per @jpengar / @bigludo7
• Generalized the error wording. Provider-specific phrasing ("no real-time profile found") is replaced with a generic message applicable to any provider.
• Removed scoring/business-logic language. "fraud decisioning / risk scoring / ML features / step-up logic" is replaced with neutral wording: the value is a technical network signal indicating recency; how a consumer uses it is up to them. — per @jpengar
• Design rationale kept in PR comments, not embedded in the spec (removed the in-spec Commonalities NOTE). — per @jpengar

Special notes for reviewers:

• Open — "no swap" representation. This PR uses 999 for "no SIM swap found." @jpengar proposed instead making the field nullable: true and returning null, keeping the enum 1–15; @bigludo7 raised whether integer + null is valid (it is, via nullable: true in OAS 3.0.x). Please confirm which you prefer and I'll align.
• Open — buckets vs. timestamp. The time-bucket vs. absolute-timestamp discussion is still pending (CC @HuubAppelboom). This PR assumes time buckets.
• 422 code. Unavailable information uses the existing SERVICE_NOT_APPLICABLE. Please confirm this is the right Commonalities code or whether a dedicated one is preferred.
• Additive. The diff shows no deletions in /check or /retrieve-date. Supersedes Update sim-swap | add /retrieve-age-band endpoint returning age band … #266 and addresses the scope concern from Update sim-swap.yaml with age band #254.

Changelog input

Added a new `POST /retrieve-age-band` endpoint returning a standardized SIM swap recency band (`simSwapAgeBand`, values 1–15, or 999 when no swap is found) as an alternative to the exact SIM swap date. Unavailable information returns 422 SERVICE_NOT_APPLICABLE. Existing `/check` and `/retrieve-date` endpoints are unchanged.

Additional documentation

This section can be blank.

This PR is opened from the feature branch KeldaAnders:feat/sim-swap-age-band-endpoint and supersedes the previously opened PR #266 which was created from main.

[HuubAppelboom]

@KeldaAnders For our largest customer (40 million accounts) requires a more granular age band (they use 72 hours). Can you add more age bands in the first week to accomodate this ?

[HuubAppelboom]

@KeldaAnders And what to return in the first 24 hours if your regulator only allows days as minimum recency ? And what is there is an upper limit that is allowed to be returned ??

[KeldaAnders]

@HuubAppelboom Thanks for sharing both points.

On finer granularity in the first week (your 72h case). Granularity at the recent end (where time-sensitive decisions cluster) is reasonable. A couple of things to align on first:

The enum is a standardized, cross-operator set (the agreement behind #253/#260), so the goal is to choose standard boundaries that let common decision thresholds land on a band edge — rather than adding customer-specific bands, which would fragment the standard and break interoperability.

Your 72h example is a good illustration of a potential gap: 72h = 3d falls inside the current 2d ≤ d < 5d band, so a consumer can't currently threshold precisely at 72h. The minimal fix is to split that band at 3d:

• 2d ≤ d < 3d
• 3d ≤ d < 5d

That makes a 72h cut expressible without any per-customer logic.

Could you share the full set of thresholds your customers actually decide on (72h noted) and the associated business value? If we collect those (e.g. 24h / 48h / 72h / 7d), I'll propose a revised standard band set to the WG that keeps fine granularity in the first days and stays coarse later.

On day-level granularity and the upper limit. First, adding a monitoredPeriod to this endpoint adds unnecessary complexity and shifts the business context of /retrieve-age-band.

The monitored-period / retention context is already fully served by /retrieve-date, which returns the exact date together with the supervision window.

So a consumer that needs the provider's monitored window — or whether the event predates it — uses /retrieve-date. Duplicating monitoredPeriod on the age-band response would change its results and semantics for no real gain, and it cuts against keeping each endpoint single-purpose.

For /retrieve-age-band specifically, that means:

• The bands are a maximal standard set; a provider is not required to populate & /or is not required to support this endpoint at all. /retrieve-age-band is an alternative, not a mandatory endpoint. If exposing the age band (or this level of granularity) isn't something a provider can or wants to support, it simply offers /check and/or /retrieve-date instead — those remain the baseline way to get SIM swap information, and a consumer falls back to them when a given provider doesn't offer the age band.

TL;DR: /retrieve-age-band stays band-only and single-purpose — an optional alternative, with /check and /retrieve-date as the fallback and the home for date/monitored-period context. Band boundaries (e.g., a 3d split for 72h) can be refined once you've shared the threshold list.

@jpengar @bigludo7 @shilpa-padgaonkar — does that separation work for you?

cc @yyeAduna, @ReidErickson-TMO @jgarciahospital,

[HuubAppelboom]

@KeldaAnders For us it is sufficient to add the 72 hours band, that seems to be the standard here, but maybe others have different use cases as well. In any case, would it hurt to add 96 hours as well ??

Regarding telco's that are only allowed a precision of at least 24 hours, I have a different proposal. In stead of returning a single band as the answer, simply allow for example "<=3" (in stead of 1, 2 or 3). That indicates that it should fall in category 1,2 or 3.

Likewise for the upper range, if you don't want to go further than for example than 1 year back, you simply provide ">=13" in stead of 13, 14 or 15.

That way it is self contained, no extra parameters are required, and these cases can also be covered.
Also, in case you have an international customer that wants a global age band api, it becomes easier to map check api's and retrieve-date api's to a single age band api.

[KeldaAnders]

@HuubAppelboom

72h / 96h bands — accepted. I'm adding both boundaries. The old 2d ≤ d < 5d band is now split into:

• 5 = 2d ≤ d < 3d (≤ 72h)
• 6 = 3d ≤ d < 4d (72h–96h)
• 7 = 4d ≤ d < 5d

That gives clean 72h and 96h cut points, and the set runs 1–17 plus 999 (no swap found). Adding 96h now costs nothing and saves a second enum change later, so agreed. If others surface further early-week thresholds, we can fold those in during the same WG pass.

On the <=3 / >=13 range notation. I'd rather not take this on, and I'd prefer we move forward with the current version and get it approved as-is.

The notation changes the response field from a plain integer to a small grammar — exact N, <=N, >=N — which means every consumer has to parse the value and we lose simple enum validation (we'd be validating against a pattern instead). Layering a comparator syntax on top now would widen the scope and risk stalling the PR over something we don't yet have a concrete requirement for.

A fixed integer band set (1–17, plus 999) is simpler to implement, validate, and consume, and it already covers the agreed use cases. If a real need for limited-precision or limited-retention encoding emerges down the line, we can revisit it as a focused follow-up rather than holding this PR for it.

@jpengar @bigludo7 @shilpa-padgaonkar — assuming the 72h/96h additions look good, can we proceed to approval?

[HuubAppelboom]

@KeldaAnders @albertoramosmonagas @yyeAduna

Regarding the minimum supported granularity, I think this must be resolved within the endpoint, otherwise API Consumer will be forced to do 2 SIM Swap calls for each check, with will double their costs.

The problem with the minimum supported granularity is that if you don't inform customers that bands are not supported, they will start questioning the data quality of all calls they do. We recently had a similar case here with a major customer that did a test with a number of random chosen phone numbers. We use retrieve-date here, but about 50% of the service providers do not support the time of day, but the date of SIM Swap is supported. The time stamp contains then 2026-06-08T22:00:00.000Z or 2026-01-08T23:00:00.000Z (depending on the implemention and conversion of local time to GMT, which depends on summertime). The customer immediately started to challenge the quality of the data, because we forgot to communicate that not all numbers support time, but only date. The customer will now detect this by looking at whether the time states 22:00:00.000, but this is not ideal.

This granularity issue for missing time information can for example be solved by adding a boolean whether time of day is supported, or optional a list of not supported bands.

Another option of course is putting in the specification that all bands must be supported by all telcos in a country, but that will impact the roll-out of age-band significantly.

[HuubAppelboom]

@KeldaAnders @albertoramosmonagas @yyeAduna
Regarding the cut-off of the upper bands. There are many telco's that don't want to go further then a specific time period. A simple solution can be to add a boolean for this as well, that the SIM Swap happened after the maximum band is willing to share. So for example, the result will be band 13, and a boolean that it is out of range (which means somewhere beyond band 13).

[albertoramosmonagas]

Thanks @KeldaAnders and @HuubAppelboom.

The clarification on activation versus actual SIM swap is helpful. Our remaining concern is granularity and historical lookback. If /retrieve-age-band returns a single enum value, consumers will expect the same taxonomy to be supported consistently across providers. Therefore, our preference is simple:

• providers exposing /retrieve-age-band should support the complete standardized band model;
• if they cannot support the required granularity or determine the correct band due to retention limitations, they should not expose this endpoint and instead rely on /check and/or /retrieve-date.

Finally, temporary backend or data-source failures should remain server-side errors rather than being mapped to 422 SERVICE_NOT_APPLICABLE.

[HuubAppelboom]

@KeldaAnders For the 999 result, it may be a good idea to add to the description that the number was also never ported. Porting also has a SIM Swap risk in it.

[KeldaAnders]

@albertoramosmonagas @HuubAppelboom Thanks for the feedback — it's much appreciated. I've made the changes and pushed them:

• Full band model required. A provider that exposes /retrieve-age-band is expected to support the complete standardized band model. If it can't meet the required granularity or determine the correct band due to retention limitations, it should not expose this operation and should rely on /check and/or /retrieve-date instead.
• Temporary failures are server-side errors. Temporary backend or data-source failures are returned as 5xx, not mapped to 422 SERVICE_NOT_APPLICABLE.
• 999 now also covers porting. 999 means the provider positively confirms a SIM swap has never happened and the number has not been ported.

Let me know if the documentation/semantic clarifications address your concerns & if the additions look good, can we proceed to review approval?

@bigludo7 @jpengar — tagging you for approval on this scope.

cc @ReidErickson-TMO, @shilpa-padgaonkar @yyeAduna

[KeldaAnders]

@bigludo7 @jpengar — Looping back to close this review out, looking to you for tagging you for approval.

[shilpa-padgaonkar]

/LGTM

[shilpa-padgaonkar]

@bigludo7 @maxl2287 @fernandopradocabrillo Could you all kindly review and approve the PR if you have no further issues? Thanks in advance.

[albertoramosmonagas]

Thanks for the continued work on this @KeldaAnders. The endpoint isolation is right and we appreciate the iterations. Still, we have blocking points before we can approve.

1. 501 NOT_IMPLEMENTED is missing — this is the core mechanism for an optional endpoint
The PR states this endpoint is optional and that providers are not expected to support it. However, POST /retrieve-age-band does not declare a 501 response. Per CAMARA design guidelines, 501 NOT_IMPLEMENTED can only be returned if it is explicitly documented in the spec. Without it, a provider that does not implement the endpoint has no standards-compliant way to signal that — a consumer will receive a 404 or undefined behavior instead of a clear, interoperable signal. This is the primary mechanism that makes optionality actually work in practice. It must be added to the endpoint's response definitions before merge.

2. 999 semantics — not tight enough — The spec still conflates "no event found in retained history" with "provider positively confirms no swap ever happened." These are different claims. 999 must mean only the latter. If lookback is limited, the provider must return 422 — or not expose the endpoint at all.

3. 999 is non-ordinal — not stated in the schema: Nothing prevents a consumer from reading 999 as "older than band 17." The schema needs an explicit statement that 999 is a sentinel, not a position in the recency sequence.

4. Open question from #266 still unresolved: 999 vs. null - Left as "please confirm which you prefer" in the PR notes — never resolved. Our position: null is the established CAMARA pattern for "value cannot be returned" (cf. latestSimChange: null in /retrieve-date). A magic integer requires special-casing by every consumer. Please resolve before merge.

5. 422 scope is too broad - "Unexpectedly missing data returns 422" is wrong. SERVICE_NOT_APPLICABLE covers structural non-applicability, not transient backend failures — those must remain 5xx.

6. Band taxonomy governance - The 72h/96h split was added in direct response to one customer's threshold. A standardized enum that adjusts to commercial thresholds is not a standard. The WG needs an objective criterion for what justifies a new band edge before any additions land in the spec.

7. "Full band model required" must be normative - The current prose is a recommendation. It needs to read as a MUST: a provider exposing this endpoint MUST support the complete standardized band model. Partial support creates false interoperability.

8. d is not defined - Band boundaries use d without defining it. UTC? 24h vs. calendar day? How are 1y/2y/3y computed — 365 days or calendar year? Leap years? Two providers computing d differently will assign different bands for the same event.

9. Version target - v2.1.0 was released on 17.09.2025 (Fall25, r3.3). A new endpoint cannot target an already-released version. Please clarify the intended release.

10. The tables render incorrectly in the reDoc -

CC: @bigludo7 @jpengar @HuubAppelboom

[KeldaAnders]

@albertoramosmonagas Thanks for the detailed review — see the point-by-point below

1. 501 NOT_IMPLEMENTED — ✅ added.
POST /retrieve-age-band now declares a 501 response, backed by a new Generic501 component (NOT_IMPLEMENTED). The spec states the operation is OPTIONAL and that a non-implementing provider returns 501 so consumers get a clear, interoperable signal and can fall back to /check / /retrieve-date.

2. "Never happened" semantics — ✅ tightened (and moved off 999).
The positive "no swap ever" value is now 111, and it means only that the provider positively confirms a SIM swap has never happened (incl. never ported). It is no longer conflated with "not found in retained history." Limited lookback is explicitly not this value — it is 422 SERVICE_NOT_APPLICABLE (structural) or the provider does not expose the operation.

3. Non-ordinal — ✅ stated in the schema.
The schema now says explicitly that 111 is a sentinel meaning "no SIM swap has ever occurred," that it is NOT a position in the recency sequence, and MUST NOT be interpreted as "older than band 17."

4. 999 vs null — 🔄 resolved, proposing 422 for the "can't determine" case.
We took your point that a magic integer shouldn't carry a "value cannot be returned" meaning. Rather than null, we've reframed that case: a valid subscriber for whom no real-time profile is available is a structural inability to serve, so it returns 422 SERVICE_NOT_APPLICABLE — which aligns with your own point 5 (structural non-applicability = 422). The only non-band value left in the 200 body is 111, a genuine positive confirmation (a real answer, so it belongs in success). Net: no nullable integer to special-case, and the three non-band outcomes are cleanly separated by status — 422 (structurally not applicable, incl. no real-time profile), 501 (not implemented), 5xx (transient). We think this is cleaner than null, but flagging it as the one open item for your confirmation.

5. 422 scope — ✅ narrowed.
SERVICE_NOT_APPLICABLE now covers structural non-applicability only. Transient backend/data-source failures MUST be returned as 5xx, never 422 — stated in the Error handling section, the schema, and the operation description.

6. Band taxonomy governance — 🔄 proposal.
Agreed a standard shouldn't flex to one customer's threshold. Our view is that a more granular standardized set has no real downside (bands are ordinal; consumers apply their own thresholds), so we don't think every edge needs to clear a formal criterion before it can land. But if the WG wants that as a precondition, let's not block the endpoint: approve /retrieve-age-band for release, I'll remove the 72h/96h additions from this PR so it merges on the agreed standard band set, and I'll open a separate amendment issue to add 72h/96h (and define the objective criterion) through the normal CAMARA governance path.

7. "Full band model" normative — ✅ now MUST.
"A provider that exposes this operation MUST support the complete standardized band model; partial support is not permitted, as it would create false interoperability." (Reflected in the description, schema, and Error handling section.)

8. d defined — ✅ added.
d is the elapsed time between the SIM swap event and the instant the request is processed, both in UTC. One day is a fixed 24 hours; 1y/2y/3y are computed as 365/730/1095 days (fixed-length, leap years not applied) so two providers assign the same band to the same event.

9. Version target — ✅ corrected.
Agreed — 2.1.0 is already released (Fall25, r3.3). This now targets 2.2.0 (MINOR over 2.1.0, backward-compatible new endpoint), URL /sim-swap/v2.

10. ReDoc tables — ✅ fixed.
Reformatted the tables (proper | --- | separators and surrounding blank lines) so they render correctly in ReDoc.

Open items for your call: # 4 (we propose 422 over null — please confirm) and # 6 (keep granular vs. remove-and-amend). Everything else is implemented.

CC: @bigludo7 @jpengar @HuubAppelboom

[albertoramosmonagas]

Hi @KeldaAnders

From our side, most of the previous blocking points are now addressed.

• On 422 versus null, we can leave the final decision to the WG. The proposed 422 approach is acceptable to us as long as the text remains explicit that 422 SERVICE_NOT_APPLICABLE is only for structural inability to determine the band, and not for temporary backend or data-source failures.

• On the 72h / 96h split, we still see the governance concern: the model remains open to commercially driven thresholds, and adding new band edges without objective criteria may create a precedent for future customer-driven changes. That said, we also leave the final decision to the WG.

A few final housekeeping points before review:

• the branch currently has conflicts that need to be resolved;
• there are still inline # comments in the YAML that should be cleaned up before review;
• and this is a question for the group, should this PR also include the test cases for the new /retrieve-age-band operation, or will those be handled in a separate PR?

CC: @fernandopradocabrillo, @bigludo7, @jpengar, @HuubAppelboom

[bigludo7]

Hello
Thanks @KeldaAnders for the contribution and the very solid answers to the pending questions.

Regarding @albertoramosmonagas question about test-cases I'm fine to have them in another PR in order to move forward with this one.

Agreed of course about the 2 other cleaning points mentioned by Alberto. As we applied all Commonalities requirements in a previous PR the cleaning will be a bit tricky bit a good exercice for an IA ;)

[PedroDiez]

Minor comments

[PedroDiez]

version and url MUST not be modified.

That is managed vía Release Automation workflow. They have to be set back to wip

[PedroDiez]

Info:

• https://github.com/camaraproject/ReleaseManagement/blob/main/documentation/README.md
• https://github.com/camaraproject/ReleaseManagement/blob/main/documentation/release-process/lifecycle.md

[PedroDiez]

Suggestion for UX improvement:

  - Definition of `d`:
    - `d` is the elapsed time between the most recent SIM swap event and the instant the request is processed, both evaluated in UTC. One day (`d`) is a fixed 24-hour period; `1y`, `2y` and `3y` are computed as 365, 730 and 1095 days respectively (fixed-length, leap years not applied) to guarantee that two providers assign the same band to the same event.

Redocly snapshot:

[KeldaAnders]

Rebased on main and resolved the conflict — the branch is clean again and CI is green. Also folded in @PedroDiez's review. Summary of what's in the latest push:

Conflict resolution

• Merged the latest main (incl. the recent Commonalities cleanup) and kept /check, /retrieve-date, and the shared schemas/error responses on main's updated content. The /retrieve-age-band additions are layered on top, so the diff stays additive.

Per @PedroDiez

• Reverted version to wip and the server URL to /sim-swap/vwip — these are managed by the Release Automation workflow and are no longer set manually.
• Restructured the Definition of d and Standardized age-band value mapping blocks as nested bullets, and moved the value list into a markdown table (renders cleanly in Redocly now).

Still open for the WG's call (happy to go either way)

• Test cases to follow in a separate PR, per @bigludo7.

@bigludo7 @fernandopradocabrillo @maxl2287 @PedroDiez — ready for another look; please let me know if anything else blocks approval.

[PedroDiez]

Comments addressed @KeldaAnders.

Minor comment regarding indentation. A way to check UX can be this:
1.- Go to view file

2.- Select 'raw' option, take the link, e.g.
https://raw.githubusercontent.com/KeldaAnders/SimSwap/b7f1acde77c6b74e3cc0869d754afa603bf22ee8/code/API_definitions/sim-swap.yaml

3.- Open redocly
https://redocly.github.io/redoc/?url=&nocors

4.- Fill with the link obtained for the API Spec, e.g.

https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/KeldaAnders/SimSwap/b7f1acde77c6b74e3cc0869d754afa603bf22ee8/code/API_definitions/sim-swap.yaml&nocors

That helps to identify renderization topics

[PedroDiez]

Review the indentation to align with the rest of examples

[KeldaAnders]

Thanks @PedroDiez for the review — much appreciated. Latest updates are pushed:

• Indentation fix — AGEBAND_2LEGS is now aligned to 4 spaces with the other examples
• Tag description — added a tag-level description for Retrieve SIM swap age band so it renders as a proper intro sentence under the section heading in ReDoc
• version / URL — kept at wip / vwip (Release Automation managed), per your earlier note.
• d definition and value mapping — restructured as nested bullets with the value table, as you suggested.

Rendered ReDoc preview of the current state: https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/KeldaAnders/SimSwap/292805c92498ac046f382ddb6c23b2eb783d078b/code/API_definitions/sim-swap.yaml&nocors#section/Request-body-strictness

@PedroDiez @bigludo7 @fernandopradocabrillo @maxl2287 — ready for another look; please let me know if anything else blocks approval.

• @shilpa-padgaonkar

[PedroDiez]

LGTM

[KeldaAnders]

Thanks all for the reviews — this is approved, and CI is green.

@bigludo7 @fernandopradocabrillo @maxl2287 (codeowners) — good to merge whenever you are.

I can leave the merge to you so it follows the repo's standard method, but I'm also happy to merge it myself if you'd prefer. Just let me know which method the sub-project uses.

[bigludo7]

LGTM
Thanks @KeldaAnders

[bigludo7]

@KeldaAnders Merged ;)

[KeldaAnders]

Thank you @bigludo7 @fernandopradocabrillo @PedroDiez & All!