swagger: "2.0" info: version: "1.0.2" title: NEMT Member API description: | RESTful API for NEMT Member App Repo: nemt-portal-api host: app.swaggerhub.com contact: name: Carlos Andrioli email: carlos@brighterdevelopment.com basePath: /v1 schemes: - http consumes: - application/json produces: - application/json securityDefinitions: AppKey: type: apiKey in: header name: App description: Application Key (use "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") only used to authenticate the application AppToken: type: apiKey in: header name: Token description: The App Bearer token. Need to make a get request to the address "/v1/authenticate" with the "App" header and the log in body tags: - name: auth description: Endpoints for system and users authentication. - name: member description: Endpoints for members of a participating payer. - name: visits description: Endpoints for visits to participating providers by members of a participating payer. - name: notifications description: Endpoints for notifications related to members, visits, providers and system state. - name: rides description: Endpoints for rides to participating providers for members of participating payers. - name: providers description: Endpoints for participating providers related to a member of a participating payer - name: messages description: Endpoints for (tbd) message types. paths: /authenticate/: post: tags: - auth summary: Authorize the application use description: Authorizes the application routes returning a JWT token for authentication operationId: authenticateApp security: - AppKey: [] parameters: - name: data in: body description: Member authentication data required: true schema: $ref: '#/definitions/AuthRequest' responses: 200: description: Get the token for application authorization schema: $ref: '#/definitions/AuthResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/visits/: get: tags: - visits - member summary: Get a filtered list of member-visits to participating providers description: Get a list of visits operationId: listVisits security: - AppToken: [] parameters: - name: page in: query description: Pagination page number default: 1 required: false type: integer format: int64 - name: quantity in: query description: Pagination quantity per page default: 10 type: integer format: int64 responses: 200: description: Visits paginated list schema: $ref: '#/definitions/VisitsPaginatedResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' post: tags: - visits - member summary: Create a visit to a participating provider for an eligible member. description: Reserves a pre-defined or arbitrary visit time range operationId: addVisit security: - AppToken: [] parameters: - name: data in: body description: Visit data required: true schema: $ref: '#/definitions/Visit' responses: 200: description: Visit object with all the ID and remanescent parameters filled schema: $ref: '#/definitions/Visit' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/visits/{visit_uuid}/: get: tags: - visits - member summary: Get details of a single member-visit to a participating provider. description: Get details of a single member-provider visit operationId: getVisitDetail security: - AppToken: [] parameters: - name: visit_uuid in: path description: Visit unique identifier type: string required: true responses: 200: description: Visit Details schema: $ref: '#/definitions/Visit' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' put: tags: - visits - member summary: Update a single member-visit to a participating provider. description: Get the member visit operationId: updatemember security: - AppToken: [] parameters: - name: visit_uuid in: path description: Visit unique identifier type: string required: true - name: data in: body description: Visit data required: true schema: $ref: '#/definitions/Visit' responses: 200: description: Visit detail schema: $ref: '#/definitions/Visit' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' delete: tags: - visits - member summary: Delete a single member-visit to a participating provider. description: Cancel a member appointment operationId: deletemember security: - AppToken: [] parameters: - name: visit_uuid in: path description: Visit unique identifier type: string required: true responses: 204: description: No return if everything works 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/members/: get: tags: - member summary: Get a filtered list of members description: Get a list of members operationId: listmembers security: - AppToken: [] parameters: - name: page in: query description: Pagination page number default: 1 required: false type: integer format: int64 - name: quantity in: query description: Pagination quantity per page default: 10 type: integer format: int64 responses: 200: description: members paginated list schema: $ref: '#/definitions/MembersPaginatedResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/members/{member_uuid}/: get: tags: - member summary: member detail description: Get a member's detail data operationId: getmemberDetail security: - AppToken: [] parameters: - name: member_uuid in: path description: member unique identifier type: string required: true responses: 200: description: member detail schema: $ref: '#/definitions/Member' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/notifications/: get: tags: - notifications - member summary: Get a list of notifications for a single member. description: Get a list of notifications for a single member. operationId: listNotifications security: - AppToken: [] parameters: - name: page in: query description: Pagination page number default: 1 required: false type: integer format: int64 - name: quantity in: query description: Pagination quantity per page default: 10 type: integer format: int64 responses: 200: description: Notification paginated list schema: $ref: '#/definitions/NotificationPaginatedResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/notifications/{notification_uuid}/: get: tags: - notifications - member summary: Get the member's notification description: Get a specific notification operationId: getNotification security: - AppToken: [] parameters: - name: notification_uuid in: path description: Notification unique identifier type: string required: true responses: 200: description: Notification detail schema: $ref: '#/definitions/Notification' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/rides/: get: tags: - rides - visits - member summary: Get a filtered list of rides for a single member. description: Get a filtered list of rides for a single member. operationId: listRides security: - AppToken: [] parameters: - name: page in: query description: Pagination page number default: 1 required: false type: integer format: int64 - name: quantity in: query description: Pagination quantity per page default: 10 type: integer format: int64 responses: 200: description: Rides paginated list schema: $ref: '#/definitions/RidePaginatedResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' post: tags: - rides - visits - member summary: Create a ride to a participating provider for an eligible member. description: Get the ride operationId: addRide security: - AppToken: [] parameters: - name: data in: body description: Book a scheduled ride with at least one ride_segment. required: true schema: $ref: '#/definitions/RideRequest' responses: 200: description: Ride object with all the ID and remanescent parameters filled schema: $ref: '#/definitions/Ride' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/rides/{ride_uuid}/: get: tags: - rides - visits - member summary: Ride detail description: Get a member's specific ride data operationId: getRideDetail security: - AppToken: [] parameters: - name: ride_uuid in: path description: Ride unique identifier type: string required: true responses: 200: description: Ride detail schema: $ref: '#/definitions/Ride' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' put: tags: - rides - visits - member summary: Update a single member-ride description: Update a single member-ride operationId: updateRides security: - AppToken: [] parameters: - name: ride_uuid in: path description: Ride unique identifier type: string required: true - name: data in: body description: Ride data required: true schema: $ref: '#/definitions/Ride' responses: 200: description: Ride detail schema: $ref: '#/definitions/Ride' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/rides/{ride_uuid}/cancel: post: tags: - rides - visits - member summary: Cancel ride description: Cancel a specific ride for a member operationId: cancelRide security: - AppToken: [] parameters: - name: ride_uuid in: path description: Ride unique identifier type: string required: true responses: 204: description: Empty response means that the cancel was aceppted 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/rides/{ride_uuid}/destination: put: tags: - rides - visits - member summary: Change the ride destination description: Change the ride destination operationId: changeRideDestination security: - AppToken: [] parameters: - name: ride_uuid in: path description: Ride unique identifier type: string required: true - name: data in: body description: Destination data required: true schema: $ref: '#/definitions/Location' responses: 200: description: Location confirmation schema: $ref: '#/definitions/Location' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/ridetypes: get: tags: - rides security: - AppToken: [] operationId: getRideTypes summary: List the ride types description: List the ride types from the database parameters: - name: lat in: query description: latitude type: number format: float required: true - name: lng in: query description: longitude type: number format: float required: true responses: 200: description: Ride Type list schema: $ref: '#/definitions/RideTypeResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/rideseta: get: tags: - rides security: - AppToken: [] operationId: getRideEta summary: Get the ETA of the Ride description: Get the ETA of the types parameters: - name: lat in: query description: latitude type: number format: float required: true - name: lng in: query description: longitude type: number format: float required: true - name: dest_lat in: query description: destination latitude type: number format: float required: true - name: dest_lng in: query description: destination longitude type: number format: float required: true - name: ride_type_uuid in: query description: ride type UUID type: string responses: 200: description: Ride ETA list schema: $ref: '#/definitions/RideETAResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/ridedrivers: get: tags: - rides security: - AppToken: [] operationId: getRideDrivers summary: Get Drivers near origin location. description: Get Drivers close to the Origin location parameters: - name: lat in: query description: latitude type: number format: float required: true - name: lng in: query description: longitude type: number format: float required: true - name: ride_type_uuid in: query description: ride type UUID type: string responses: 200: description: Ride Drivers list schema: $ref: '#/definitions/RideDriverResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/providers/: get: tags: - rides - providers - member summary: Get providers description: Get a list of providers operationId: getProviders security: - AppToken: [] parameters: - name: page in: query description: Pagination page number default: 1 required: false type: integer format: int64 - name: quantity in: query description: Pagination quantity per page default: 10 type: integer format: int64 responses: 200: description: Provider list schema: $ref: '#/definitions/ProviderPaginatedResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' /nemt/providers/{lat}/{lng}/: get: tags: - rides - providers - member summary: Provider by Location description: Get a list of providers for a current location operationId: getProvidersByLocation security: - AppToken: [] parameters: - name: lat in: path description: latitude type: number format: float required: true - name: lng in: path description: longitude type: number format: float required: true - name: page in: query description: Pagination page number default: 1 required: false type: integer format: int64 - name: quantity in: query description: Pagination quantity per page default: 10 type: integer format: int64 responses: 200: description: Provider list schema: $ref: '#/definitions/ProviderPaginatedResponse' 401: description: Unauthorized access schema: $ref: '#/definitions/DefaultErrorResponse' 422: description: Validation error schema: $ref: '#/definitions/DefaultErrorResponse' 503: description: Service Unavailable schema: $ref: '#/definitions/DefaultErrorResponse' definitions: DefaultErrorResponse: type: object description: Default error response data properties: error: type: boolean description: Indicates if the response is an error message: type: string description: Detailed response message AuthRequest: type: object description: Request from application authrization properties: email: type: string description: Member e-mail password: type: string description: Base64 encoded password AuthResponse: type: object description: Response from application authrization properties: token: type: string description: The token string for app authorization valid_time: type: integer format: int64 description: Token expiration time in Unix time format server_time: type: integer format: int64 description: Server time in Unix time format PaginatedResponse: type: object description: Paginated response data properties: pagination: type: object description: Pagination data properties: total_records: type: integer format: int64 description: Total result count records_per_page: type: integer format: int64 description: Max records per page total_pages: type: integer format: int64 description: Total page count current_page: type: integer format: int64 description: Current page number data: type: array items: type: object description: Paginaged data Member: type: object description: member data properties: member_uuid: type: string description: member unique ID name: type: string description: Name phone_number: type: string description: Phone number MembersPaginatedResponse: type: object description: members paginated response data allOf: - $ref: '#/definitions/PaginatedResponse' - properties: data: type: array items: $ref: '#/definitions/Member' Driver: type: object description: Driver data properties: driver_uuid: type: string description: Driver unique ID name: type: string description: Full Name (?) phone_number: type: string description: Vehicle Brand model: type: string description: Vehicle Model plate: type: string description: Vehicle Plate color: type: string description: Vehicle Color Visit: type: object description: Details of a member-visit to a participating proivider. properties: visit_uuid: type: string description: Unique Visit ID VisitsPaginatedResponse: type: object description: Paginated list of Visits. allOf: - $ref: '#/definitions/PaginatedResponse' - properties: data: type: array items: $ref: '#/definitions/Visit' Notification: type: object description: Notification data properties: notification_uuid: type: string description: Notification unique ID notification: type: string description: Notification message is_read: type: boolean description: Verify if the message was read NotificationPaginatedResponse: type: object description: Notification paginated response data allOf: - $ref: '#/definitions/PaginatedResponse' - properties: data: type: array items: $ref: '#/definitions/Notification' RideRequest: type: object description: Request a scheduled ride with at least one ride_segment. properties: ride_type: type: object description: Ride Type. For on-demand requests, Dispatch supports lyft, lyft_plus, lyft_premier, lyft_lux, and lyft_luxsuv. For scheduled rides Dispatch only supports lyft type rides. $ref: '#/definitions/RideType' visit_uuid: type: string description: Unique Visit ID. origin: type: object description: Scheduled starting location of ride segment. $ref: '#/definitions/Location' destination: type: object description: Ending location of ride segment. $ref: '#/definitions/Location' scheduled_pickup_range: type: object description: Scheduled time for Pickup. $ref: '#/definitions/scheduled_pickup_range' Ride: type: object description: Information about a single ride for a member of a participating payer to a participating provider. properties: ride_uuid: type: string description: Unique Ride ID. ride_type: type: object description: Ride Type. For on-demand requests, Dispatch supports lyft, lyft_plus, lyft_premier, lyft_lux, and lyft_luxsuv. Ride Types; for scheduled rides Dispatch only supports lyft rides. $ref: '#/definitions/RideType' ride_status: type: object description: Ride Status. $ref: '#/definitions/RideStatus' requested: type: string format: datetime description: Request Date. driver: type: object description: Driver information. $ref: '#/definitions/Driver' locations: type: object description: Location information. $ref: '#/definitions/locations' locations: type: object description: Ride location properties. properties: origin: type: object description: Starting location of ride segment. $ref: '#/definitions/Location' dropoff: type: object description: Actual Dropoff locationof ride segment. $ref: '#/definitions/Location' currentLocation: type: object description: Current or last known actual location of vehicle. $ref: '#/definitions/Location' destination: type: object description: Ending location of ride segment. $ref: '#/definitions/Location' scheduled_pickup_range: type: object description: Object that must be included for scheduled rides. Optional otherwise. Follows Lyft conventions. Returned only for Scheduled Rides. properties: scheduled_pickup_range.timestamp_ms: type: number format: float description: Date and time of the pickup in milliseconds. enum: [600000] scheduled_pickup_range.range_ms: type: number format: int description: Range of the pickup time in milliseconds. enum: [1472558400000] Location: type: object description: Actual reported location of vehicle at time of report (versus scheduled origin, destination, etc.) properties: lat: type: number format: float description: Latitude enum: [37.795546] lng: type: number format: float description: Longitude enum: [-122.393420] address: type: string description: Full Address as single line. enum: [568 Brannan St, San Francisco, CA 94107, USA] eta: type: number format: float description: Estimated time is seconds until vehicle arrival. enum: [3600] RidePaginatedResponse: type: object description: Paginated list of Rides. allOf: - $ref: '#/definitions/PaginatedResponse' - properties: data: type: array items: $ref: '#/definitions/Ride' Provider: type: object description: Provide data properties: provider_uuid: type: string description: Unique Provider ID npi_id: type: integer description: National Provider ID provider_name: type: string description: Provider Name address: type: string description: Provider Address lat: type: number format: float description: Latitude lng: type: number format: float description: Longitude ProviderPaginatedResponse: type: object description: Paginated list of Providers allOf: - $ref: '#/definitions/PaginatedResponse' - properties: data: type: array items: $ref: '#/definitions/Provider' RideType: type: object description: Object containing detailed info on type of the TNC ride. properties: ride_type_uuid: type: string description: Internal UUID of the ride type. ride_type: type: string enum: [lyft, lyft_line,lyft_plus,lyft_premier.lyft_lux,lyft_luxsuv] description: Internal type of the ride. For on-demand requests, Dispatch supports lyft, lyft_plus, lyft_premier, lyft_lux, and lyft_luxsuv. Ride Types; for scheduled rides Dispatch only supports lyft rides. display_name: type: string description: User-facing description of a TNC Ride type. enum: [Lyft, Lyft Line,Lyft Plus,Lyft Premier, Lyft Lux,Lyft Luxsuv] image_url: type: string description: Full URL of icon for ride type for display on map, etc. enum: [https://cdn.lyft.com/assets/Vehicle_plus.png] RideStatus: properties: ride_status_uuid: type: string description: UUID of the ride status entry. ride_status: type: string description: Internal description of ride status. enum: [pending,accepted,arrived,pickedUp,droppedOff, canceled,failed] display_name: type: string description: User-facing description Ride Status enum: [Pending,Accepted,Arrived,Picked Up,Dropped Off, Canceled,Failed] status_description: type: string description: User-facing description of Ride Status. enum: [A passenger's ride request has been made and Lyft is matching the passenger to a driver., A driver has accepted the ride., The driver has arrived at the pickup location.,The driver has picked up the passenger.,The driver has dropped off the passenger., The ride has been canceled. In this ride state the additional field canceled_by indicates whether the ride was canceled by the driver passenger or no_drivers_available if no driver could be found for the ride.,Unknown system error occurred. Exceptionally rare.] RideTypeResponse: type: array description: List of the Ride Types items: $ref: '#/definitions/RideType' RideETA: properties: ride_type_uuid: type: string description: Internal UUID of the ride type ride_type: type: string enum: [lyft, lyft_line,lyft_plus,lyft_premier.lyft_lux,lyft_luxsuv] description: Internal type of the ride. For on-demand requests, Dispatch supports lyft, lyft_plus, lyft_premier, lyft_lux, and lyft_luxsuv. Ride Types; for scheduled rides Dispatch only supports lyft rides.] display_name: type: string description: Ride Type eta_seconds: type: number description: Estimated seconds remaining until pickup from origin enum: [360] RideETAResponse: type: array description: List of the Ride ETA's items: $ref: '#/definitions/RideETA' RideDriver: properties: ride_type_uuid: type: string description: Internal UUID of the ride type ride_type: type: string description: Service of the TNC ride. display_name: type: string description: Ride Type drivers: type: array description: Drivers' locations items: $ref: '#/definitions/Location' RideDriverResponse: type: array description: List Drivers by type items: $ref: '#/definitions/RideDriver'