Hi All,
I am reading the following definition of return values:
endpoint:

Currently it states:

POST retrieve-date: Provides timestamp of latest device swap for a given phone number. If no device swap has been performed, the API will return the first phone number usage in the device (the timestamp of the first time that the phone number was connected to the network, it is, the first time that the SIM is installed in the device) by default, unless this is not possible due to local regulations preventing the safekeeping of the information for longer than the stated period. If this is the case, a null value will be returned.
POST check: Checks if device swap has been performed during a past period (defined in the request with 'maxAge' attribute) for a given phone number, the API will return boolean response (true/false), indicating that the device has been swapped or not in the specified period

I think we can improve it:

1. We can consider the case for which the SIM has been bought but never used (i.e., never put into a mobile phone).
2. We can consider some edge cases for which the mobile phone is not able to retrieve the IMEI.
3. Given that the API is returning a JSON string, I wonder if is more clear to say that the return value will be the empty string instead of the null value.
4. We need to define the check endpoint return value in case the device swap date is null (empty)

So my proposal is:

POST retrieve-date: Provides timestamp of latest device swap for a given phone number. If no device swap has been performed, the API will return the first phone number usage in the device (the timestamp of the first time that the phone number was connected to the network, it is, the first time that the SIM is installed in the device) by default. It will return an empty string in case is not possible to retrieve the date (e.g., in case the SIM has never been installed in the device, or in case local regulations are preventing the safekeeping of the information for longer than the stated period, or in some edge error cases)

POST check: Checks if device swap has been performed during a past period (defined in the request with 'maxAge' attribute) for a given phone number, the API will return boolean response (true/false), indicating that the device has been swapped or not in the specified period. It will return an empty string in case it is not possible to retrieve the device change date.

What do you think?