Clarification on how the use the Number Recycling API

[HuubAppelboom]

I think the documentation for Number Recycling can be improved, by adding a time line what can happen from the view of the API Consumer, and how the API should be used, what information can be returned (including error codes), and what scenarios could happen.

The current timelines show it very much from the telco viewpoint (but the API Consumer does not have this information)

[albertoramosmonagas]

Hi @HuubAppelboom, thanks for opening the issue. From TEF's side, totally agree that NV docs could be improved. The current docs explains the API at a high level, but ir dos not provide enough operational guidance on how an API consumer should use it over time. I think this would be useful to enrich the docs with:

• a consumer-oriented timeline or flow, like we've in the whitepaper image,
• clearer guidance on how to use specifiedDate,
• scenario-based examples showing possible outcomes,
• a better explanation of returned information and error codes,
• and finally a terminology section, since terms such as Operator, MNO, and ASP are used inconsistently today and this can create confusion for readers

At the same time, I think this work should remain focused on improving clarity for API consumers, and should not be used to redefine the API behavior itself through documentation alone. Any normative change in semantics should still be handled through the API specification and the corresponding alignment in the group. This issue is a good candidate to be included in the API scope for Sync26