How To Login

This document will highlight how to obtain a key to connect to the ParaPlan API.

Request a key by passing in the user's email address, their password encoded in SHA-512 and the calling app name. This will give you back a token and a restURL.

Note
The restURL may change, so be sure not to hard code it.

Sign future requests with the key and the same device name. This token is good for 12 hours. All results have a tokenExists and tokenIsValid bool property that can be queried for token status. You can also refresh a token without making the user login.

Postman is good for API testing (https://www.getpostman.com)

Usage

Note
When authenticating with username and password, the API will return token to sign calls AND a restURL. Use the restURL to prefix future calls.

Caution
Be sure to pass in DeviceType to receive push notifications. Valid values are APN (iOS) and FCM (Android).

How to get a key:

Send a GET request to:Login(String, String, String, String, String, String, String)

Copy

1var loginUrl = $"https://aws.engraph.com/ParaPlanREST/UserService/Login?UserName={email}&Password={password}&Device=connect-web&Version=0.1&DeviceToken=none&UTCOffset=-4&DeviceType=APN";
2using (WebClient client = new WebClient())
3{
4    string s = client.DownloadString(loginUrl);
5    var token = JsonConvert.DeserializeObject<UserToken>(s);
6
7}

It will return back an object (UserToken) with information about your login that will look like:

json

Copy

{
  "errorMessage": "",
  "success": true,
  "tokenExists": true,
  "tokenIsValid": true,
  "AssignedRoute": "DEMO-1",
  "AssignedTimes": "8:00 AM - 1:09 PM",
  "AssignedTripCount": "6 Trips",
  "AssignedVehicle": "2007 Trek Pilot 1.2 (311)",
  "AvailableFundingSources": null,
  "CanCallClients": false,
  "CanCancel": true,
  "CanScheduleTrips": true,
  "CanViewVehicles": true,
  "ClientCanRequestTrips": true,
  "ClientID": 19466,
  "CollectGPS": false,
  "CopayPaymentTypes": [
    "Not Cash",
    "Voucher",
    "Ticket",
    "Credit Card"
  ],
  "CurrentDriverBreakID": 0,
  "DatabaseID": 0,
  "DefaultPaymentType": "Voucher",
  "DeviceToken": null,
  "Key": "ca4369c1-1dca-4902-b8d5-e32235b339ff",
  "LocalDriverID": 157,
  "Name": "Tim Hibbard",
  "PPPAccess": 1,
  "ProviderCanRequestTrips": false,
  "ProviderCanViewClientDetails": false,
  "ProviderPrograms": "",
  "ProviderProgramsList": null,
  "RESTUrl": "https://aws.engraph.com/ParaPlanREST/",
  "UserId": 294,
  "UserType": 0
}

Note
PPPAccess determines if a user can have access to the ParaPlan Passenger Portal. Possible values are: 0 = Not Registered 1 = Is registered and has access 2 = User is blocked from Portal 3 = User has failed validation and needs dispatcher intervention

Note

PPPAccess determines if a user can have access to the ParaPlan Passenger Portal.

Possible values are:
0 = Not Registered
1 = Is registered and has access
2 = User is blocked from Portal
3 = User has failed validation and needs dispatcher intervention

Note
UserType indicates the type of user logging in. Possible values are: 0 = Driver 1 = Mobility Manager 2 = Rider

Note

UserType indicates the type of user logging in.

Possible values are:
0 = Driver
1 = Mobility Manager
2 = Rider

How to refresh a token

If an API call returns tokenIsValid == false and tokenExists == true, then you can refresh the token.

Send a GET request to:RefreshToken(String, String, String, String)

Refresh

Copy

1var refreshUrl = $"{storedRESTUrl}/UserService/RefreshToken?Token={expiredToken}&UserName={email}&Password={SHA-512_encoded_password}&Device={App_Name}";
2using (WebClient client = new WebClient())
3{
4    string newToken = client.DownloadString(refreshUrl);
5
6}

Tip
The JSON needs to have the key in double quotes. So "apptTime" : value, "clientFirstName" : "Jon Smith",...

Tip
Numbers do not need to be encased in quotes, but bools do. So "clientInWC" : "false" ... (https://jsonlint.com is good for json validation)

Tip
nil is not an accepted value. Use null instead.