# Additional Use Cases

## Eligibility

GTAF MAY issue the following eligibility request to check whether a user is
eligible to purchase a plan.

    GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}

Note that `planId` is the unique identifier for the plan that can be used to
purchase the plan on behalf of the user (See [Data Purchase](https://developers.google.com/mobile-data-plan/additional_use_cases#data-purchase)).
If `planId` is not specified the DPA MUST return all plans purchasable by that
user.

[Error cases](https://developers.google.com/mobile-data-plan/dpa_error_cases) lists the responses expected from DPA in case
of an error. Additionally, the DPA SHALL return an error in the following error
cases:

- The DPA returns a 400 BAD REQUEST error code indicating to GTAF that `planId` is invalid.
- The DPA returns a 409 CONFLICT error code indicating that `planId` is incompatible with the user's data plan.

Otherwise, the DPA SHALL return a 200-OK response. The format of a successful
[EligibilityResponse](https://developers.google.com/mobile-data-plan/reference/rest/v1/EligibilityResponse) is:

    {
      "eligiblePlans":
      [
       {
        "planId": string,   // Plan identifier. Can be used to
                            // refer to the plan during
                            // offers, etc. (req.)
       }
      ]
    }

When the request includes a `planId` the response includes only that
plan. Otherwise, the list includes all the plans the user is eligible to
purchase. In the case where `planId` is empty and the DPA does not support
returning the list of eligible plans it MUST return a 400 BAD REQUEST error.

## Android 5G Experiences

GTAF enables carriers to share meteredness status per connection type for
subscribers. The information can be pulled periodically by GTAF or carriers can
push the information based on internal triggers.

### Pull API

Device can pull the meteredness information via GTAF using the following:

    GET DPA/{userKey}/planStatus?key_type={userKey}&client_id=AndroidSystemInfo

Note that DPA (Data Plan Agent) represents an API GW or Entitlement server in
carrier's network.

userKey is the authentication token established during the initial auth phase
as defined [here](https://developers.google.com/mobile-data-plan/establishing_cpid).

client_id is [AndroidSystemInfo](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#androidsysteminfo)

[Meteredness](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.Meteredness) status is provided as an ENUM

DPA shall return 200 OK response and include [planInfoPerClient](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#planinfoperclient)
Error handling for DPA is defined [here](https://developers.google.com/mobile-data-plan/dpa_error_cases)

In the pull model, GTAF acts as a client and validates DPA's SSL certificate.
GTAF authenticates itself to DPA using OAuth procedure defined [here](https://developers.google.com/mobile-data-plan/OAuth_agent_api).

### Push API

Carrier can also push the meteredness information using following based on a
trigger event e.g. change of price plan, etc.

    POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/AndroidSystemInfo/users/abcdef/planStatus

DPA shall include [planInfoPerClient](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#planinfoperclient) in the body of the message.
Error responses from GTAF are defined [here](https://developers.google.com/mobile-data-plan/dataplansharing_error_cases)

In the push mode, GTAF authenticates incoming requests from DPA using the [Google Cloud OAuth2 server](https://developers.google.com/identity/protocols/oauth2/service-account). The incoming requests must be authenticated as a service account that has been whitelisted in the [ISP Portal](https://isp.google.com) for the ASN the DPA represents. Also, refer to the integration guide [here](https://developers.google.com/mobile-data-plan/api_access) for further details.