diff --git a/documentation/API_documentation/Device Identifier User Story.md b/documentation/API_documentation/Device Identifier User Story.md new file mode 100644 index 0000000..99720b0 --- /dev/null +++ b/documentation/API_documentation/Device Identifier User Story.md @@ -0,0 +1,21 @@ +# Device Identifier API User Story + +| **Item** | **Details** | +| ---- | ------- | +| ***Summary*** | As an application developer belonging to an enterprise, I want my application server to be able to request the identity of the mobile device (represented by the IMEI) currently being used by a given mobile network subscriber (identified by MSISDN, IP address or, when supported by network operators, a Network Access Identifier). Optionally, I'd like to know the make and model of that device. | +| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application Service Providers, Hyperscalers, Application Developers, End Users
**Scope:** *Order To Activate (OTA)* \- Retrieve device identifier details | +| ***Pre-Conditions*** |The preconditions are listed below:
  1. The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.
  2. The Customer:BusinessManager has successfully subscribed to the Device Identifier product from the product catalog.
  3. The Customer:Administrator has onboarded the Customer:User to the platform.
  4. The Customer:BusinessManager has agreed to the terms and conditions of the CSP for managing consent of mobile subscription owners.
  5. The means to get the access token are known to the Customer:User to ensure secure access of the API.| +| ***Activities/Steps*** | **Starts when:** The Customer:User's application server makes a POST request to the Device Identifier API containing the end user's subscription information in the request body in order to retrieve the device identifier plus any optional device information.
    **Ends when:** The Device Identifier API returns the requested information, or an error message | +| ***Post-Conditions*** | None | +| ***Exceptions*** | Several exceptions might occur after a request to the Device Identifier API
    - **Unauthorized**: Invalid credentials (e.g. use of already expired access token).
    - **Invalid Input**: Invalid input data to retrieve device details (e.g. MSISDN format not as expected, or MSISDN not associated with a customer of the CSP).
    - **Forbidden**: End user has not consented to device identifier information being provided to the Customer:User| + +# Device Type API User Story + +| **Item** | **Details** | +| ---- | ------- | +| ***Summary*** | As an application developer belonging to an enterprise, I want my application server to be able to request details about the type of the mobile device (represented by the Type Approval Code - TAC) currently being used by a given mobile network subscriber (identified by MSISDN, IP address or, when supported by network operators, a Network Access Identifier). Optionally, I'd like to know the make and model of that device. | +| ***Roles, Actors and Scope*** | **Roles:** Customer:User
    **Actors:** Application Service Providers, Hyperscalers, Application Developers, End Users
    **Scope:** *Order To Activate (OTA)* \- Retrieve device type details | +| ***Pre-Conditions*** |The preconditions are listed below:
    1. The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.
    2. The Customer:BusinessManager has successfully subscribed to the Device Type product from the product catalog.
    3. The Customer:Administrator has onboarded the Customer:User to the platform.
    4. The Customer:BusinessManager has agreed to the terms and conditions of the CSP for managing consent of mobile subscription owners.
    5. The means to get the access token are known to the Customer:User to ensure secure access of the API.| +| ***Activities/Steps*** | **Starts when:** The Customer:User's application server makes a POST request to the Device Type API containing the end user's subscription information in the request body in order to retrieve the device TAC plus any optional device information.
      **Ends when:** The Device Type API returns the requested information, or an error message | +| ***Post-Conditions*** | None | +| ***Exceptions*** | Several exceptions might occur after a request to the Device Type API
      - **Unauthorized**: Invalid credentials (e.g. use of already expired access token).
      - **Invalid Input**: Invalid input data to retrieve device details (e.g. MSISDN format not as expected, or MSISDN not associated with a customer of the CSP).
      - **Forbidden**: End user has not consented to device TAC information being provided to the Customer:User|