Is this service valid only for recycled numbers?

[StefanoFalsetto-CKHIOD]

The API specification is defining the "common scenario" which is considering a change in association between MSISDN and user owning it.

NumberRecycling/code/API_definitions/number-recycling.yaml

Line 6 in 754b6de

A common scenario is when Application service provider (ASP) wants to check whether there has been a change in the user associated with the phone number after the specified date. This allows the ASP to ensure that a phone number is correctly linked to an user and prevent the mis-delivery of SMS messages.

I would like to have a confirmations: What is the definition of "change"? I mean, is the date returned regarding the event in time when the MSISDN has been reassigned or when the MSISDN has been deactivated? The reason of my question is that MNOs are waiting weeks or months before reassigning a MSISDN to a new customer so there is a big difference between those two events. And both of them can be considered as "change in the subscriber associated with the specific phone number".

Many thanks.

[yamamoto0104]

Dear @StefanoFalsetto-CKHIOD. Thank you for your question.
The definition of "change" means the date returned regarding the event in time when the MSISDN has been reassigned to a user.
If you want to clarify the definition, please refer to the two scenarios described in YAML file.

[StefanoFalsetto-CKHIOD]

Thank you @yamamoto0104. So this service will not be useful in case an MNO needs to wait weeks or months between a number is deactivated and the same number is recycled. In that case, the SMS will be sent to a no more working number. Am I right?

[yamamoto0104]

Dear @StefanoFalsetto-CKHIOD . No, we can use the API for the terms between a number is deactivated and the same number is recycled.
Please see the following NOTE in scenario 2 of YAML file. The NOTE covers the case above.

Note: When the API receives a request with specified date during which there is no contract with MNO for the phone number, the API respond sets to 'true'(e.g., the period between 2024-02-25 and 2024-09-20 in the Scenario 2 of the figure above).

[StefanoFalsetto-CKHIOD]

Thank you @yamamoto0104 but there is something I cannot understand.
This service is called "number recycled" and you define "change" as follows:

the date returned regarding the event in time when the MSISDN has been reassigned to a user

But it returns true even when the number is not recycled, hence when the change is not yet happened.

What am I missing?

[yamamoto0104]

Dear @StefanoFalsetto-CKHIOD . The definition of true and false in YAML file shows as follow:

        phoneNumChanged:
          type: boolean
          description: |
            Set to true (Boolean, not string) when there has been a change in the subscriber associated with the specific phone number after “specifiedDate”.

[yamamoto0104]

Dear @StefanoFalsetto-CKHIOD . My explanation may not be clear. The service provider sends a request with specific date and phone number, And API returns the response with true or false, indicating that there has been a change in the user associated with the phone number.

[StefanoFalsetto-CKHIOD]

Perfect, that's the point.

For what I understand, given the aim of this service, we can consider two different events:

1. A MSISDN has been "detached from the end customer" by the MNO for some reasons (e.g., contract expired, no SIM activity and no top-up after X months, etc.). Let's call this event in time the "last_deactivated" date.
2. A MSISDN previously detached (see bullet 1) has been "re-attached to an end customer" (i.e., the MSISDN has been recycled). Let's call this event in time the "recycled date".

Hence, the phoneNumChanged attribute is returning "true" sometimes for event #1 and sometimes for event #2.

Maybe we can discuss on how to improve the current implementation by managing differently the two events, which are enabling different business opportunities.

That's a picture about the use of "last_deactivated" event:

The leftmost event in this timeline is the oldest "deactivation date" saved into the MNO BSS. Let's call it the "tracking since date". That’s an important information since it is representing how reliable the “last_deactivated” date is. For example, consider an MNO that started recording deactivated numbers only one month ago, and an MSISDN that was deactivated a year ago. In this case, the MNO would not recognize the MSISDN as "deactivated". And if it has not been re assigned to anyone, it will still be associated to the latest owner. However, the "tracking_since” date (which, in this example, is quite recent) enables the API Consumer to gather enough context to decide whether additional checks are needed before sending an SMS.

[yamamoto0104]

Dear @StefanoFalsetto-CKHIOD . Thank you for your detailed explanation.

The primary focus of Number Recycling API is to prevent misdelivery of SMS messages from service provider. Therefore, even if the service provider sets a deactivated date, the API can return “true” to prevent misdelivery of SMS messages. For this reason, we do not intend to return the deactivated date as a parameter of the API.

The Number Recycling YAML file has been discussed since the beginning of October and it was agreed and merged into repositories two weeks ago, including scenarios and error handling. If we discuss additional features now, it will not be in time for the Spring 25 Meta-release. Therefore, it would be better to discuss this issue and corresponding use cases in Fall 25 Meta-release.

[StefanoFalsetto-CKHIOD]

Thank you, dear @yamamoto0104 for your answer.

You kindly clarified to me when the API can return "true", that's why this service currently is missing some quite important business opportunity. And that's also preventing the API adoption.

So we are in a sort of code freeze up until Spring 2025 Meta-release? How many weeks we need to wait before we can start talking about improving this service?

I am not proposing to change the behavior of this service, I am proposing to just to add a couple of attributes to differentiate the business offer.

[Masa8106]

Dear @StefanoFalsetto-CKHIOD

Thank you for your comment. Based on business opportunity in the user story and scenario we have discussed, we develop the YAML file and specify when the API can return "true", as my colleague mentioned.

I am not sure what is missing business opportunity you addressed. However, if different business opportunity which is missed currently will be covered by your proposal to add a couple of attributes, I have an impression that it may be corresponding to the scope enhancement.

[HuubAppelboom]

@Masa8106 @StefanoFalsetto-CKHIOD I think there is a problem with the current YAML file. Number Recycling should target API Consumers that have previously interacted with an end user and their phone number. The idea is to check whether the same end user is still using the phone number. So, per definition, the input the API Consumer should per definition always be the date when he last interacted with the phone number by for example sending an SMS to it. If this is indeed the case, and you provide a boolean "when there has been a change in the subscriber associated with the specific phone number after “specifiedDate”, you run the risk that API Consumers also start using the same API for trying to figure out whether there is a new potential customer using that phone number. I don't think we should permit this because of privacy reasons in the same API. If you give an API Consumer submits a date at which the phone was not in use (anymore), the API should return an error, because the input is false. The API Consumer also knows then that he should not send an SMS to that number, which is sufficient.