openapi: 3.1.0
info:
  title: Lyft Concierge Concierge Rides API
  description: The Lyft Concierge API allows organizations to request rides on behalf of their customers, patients, or employees without requiring those individuals to have a Lyft account. It is designed for enterprise use cases such as healthcare patient transportation, corporate employee transit, and customer service scenarios. The API enables organizations to build customized transportation workflows, schedule rides in advance, track ride status in real time, and manage ride programs at scale. It provides a way to embed Lyft's driver network directly into business operations and third-party applications.
  version: '1.0'
  contact:
    name: Lyft Business Support
    url: https://www.lyft.com/developers
  termsOfService: https://www.lyft.com/terms
servers:
- url: https://api.lyft.com/v1
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Concierge Rides
  description: Endpoints for creating, scheduling, tracking, and managing rides on behalf of passengers who may not have a Lyft account.
paths:
  /concierge/rides:
    get:
      operationId: listConciergeRides
      summary: List concierge rides
      description: Returns a list of rides created through the concierge program. Results can be filtered by status, time range, and passenger information. Supports pagination for large result sets.
      tags:
      - Concierge Rides
      parameters:
      - name: status
        in: query
        description: Filter rides by their current status.
        required: false
        schema:
          $ref: '#/components/schemas/ConciergeRideStatusEnum'
      - name: start_time
        in: query
        description: Return rides scheduled or requested after this time. ISO 8601 format.
        required: false
        schema:
          type: string
          format: date-time
      - name: end_time
        in: query
        description: Return rides scheduled or requested before this time. ISO 8601 format.
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: Maximum number of rides to return per page.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        description: Number of rides to skip for pagination.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Successful response with concierge ride list
          content:
            application/json:
              schema:
                type: object
                properties:
                  rides:
                    type: array
                    description: List of concierge rides matching the filter criteria.
                    items:
                      $ref: '#/components/schemas/ConciergeRide'
                  total:
                    type: integer
                    description: Total number of rides matching the filter criteria.
        '400':
          description: Bad request - invalid filter parameters
        '401':
          description: Unauthorized - invalid or missing access token
    post:
      operationId: createConciergeRide
      summary: Create a concierge ride
      description: Creates a new ride on behalf of a passenger. The passenger does not need to have a Lyft account. Rides can be dispatched immediately or scheduled for a future pickup time. The request must include the passenger's contact information, pickup location, and destination.
      tags:
      - Concierge Rides
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConciergeRideRequest'
      responses:
        '200':
          description: Concierge ride created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConciergeRide'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing access token
        '422':
          description: Unprocessable entity - validation error
  /concierge/rides/{id}:
    get:
      operationId: getConciergeRide
      summary: Get concierge ride detail
      description: Returns the details of a specific concierge ride, including current status, passenger information, driver and vehicle details, and route information.
      tags:
      - Concierge Rides
      parameters:
      - $ref: '#/components/parameters/rideId'
      responses:
        '200':
          description: Successful response with ride details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConciergeRide'
        '401':
          description: Unauthorized - invalid or missing access token
        '404':
          description: Ride not found
  /concierge/rides/{id}/cancel:
    post:
      operationId: cancelConciergeRide
      summary: Cancel a concierge ride
      description: Cancels a concierge ride that has been requested or scheduled. Rides that have already been completed cannot be canceled. Cancellation fees may apply depending on the ride's current status and how long a driver has been assigned.
      tags:
      - Concierge Rides
      parameters:
      - $ref: '#/components/parameters/rideId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                cancel_confirmation_token:
                  type: string
                  description: A token required to confirm cancellation when a fee applies.
      responses:
        '204':
          description: Ride canceled successfully
        '400':
          description: Bad request - ride cannot be canceled
        '401':
          description: Unauthorized - invalid or missing access token
        '404':
          description: Ride not found
  /concierge/rides/{id}/status:
    get:
      operationId: getConciergeRideStatus
      summary: Get concierge ride status
      description: Returns the current status and real-time tracking information for a concierge ride, including driver location when a driver is assigned.
      tags:
      - Concierge Rides
      parameters:
      - $ref: '#/components/parameters/rideId'
      responses:
        '200':
          description: Successful response with ride status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConciergeRideStatus'
        '401':
          description: Unauthorized - invalid or missing access token
        '404':
          description: Ride not found
components:
  schemas:
    ConciergeVehicle:
      type: object
      description: Information about the vehicle assigned to a concierge ride.
      properties:
        make:
          type: string
          description: Vehicle manufacturer name.
        model:
          type: string
          description: Vehicle model name.
        year:
          type: integer
          description: Vehicle model year.
        license_plate:
          type: string
          description: Vehicle license plate number.
        color:
          type: string
          description: Color of the vehicle.
    ConciergePrice:
      type: object
      description: Price information for a concierge ride.
      properties:
        amount:
          type: integer
          description: Total price in the smallest denomination of the currency.
        currency:
          type: string
          description: ISO 4217 currency code.
          pattern: ^[A-Z]{3}$
        description:
          type: string
          description: Human-readable description of the price.
    ConciergeDriver:
      type: object
      description: Information about the driver assigned to a concierge ride.
      properties:
        first_name:
          type: string
          description: The driver's first name.
        phone_number:
          type: string
          description: The driver's contact phone number.
        rating:
          type: string
          description: The driver's average rating.
        image_url:
          type: string
          format: uri
          description: URL to the driver's profile photo.
    Location:
      type: object
      description: A geographic location with optional address details.
      required:
      - lat
      - lng
      properties:
        lat:
          type: number
          format: double
          description: Latitude of the location.
        lng:
          type: number
          format: double
          description: Longitude of the location.
        address:
          type: string
          description: Street address of the location.
        city:
          type: string
          description: City name.
        state:
          type: string
          description: State or province code.
        zip:
          type: string
          description: Postal code.
    ConciergeRide:
      type: object
      description: Detailed information about a concierge ride including its current status, passenger, driver, vehicle, and route information.
      properties:
        ride_id:
          type: string
          description: Unique identifier for the concierge ride.
        ride_type:
          type: string
          description: Identifier for the type of ride.
        status:
          $ref: '#/components/schemas/ConciergeRideStatusEnum'
        passenger:
          $ref: '#/components/schemas/Passenger'
        origin:
          $ref: '#/components/schemas/Location'
        destination:
          $ref: '#/components/schemas/Location'
        driver:
          $ref: '#/components/schemas/ConciergeDriver'
        vehicle:
          $ref: '#/components/schemas/ConciergeVehicle'
        scheduled_pickup_time:
          type: string
          format: date-time
          description: The scheduled pickup time, if the ride was scheduled in advance.
        requested_at:
          type: string
          format: date-time
          description: Timestamp when the ride was created.
        completed_at:
          type: string
          format: date-time
          description: Timestamp when the ride was completed.
        canceled_at:
          type: string
          format: date-time
          description: Timestamp when the ride was canceled, if applicable.
        price:
          $ref: '#/components/schemas/ConciergePrice'
        notes:
          type: string
          description: Special instructions provided when the ride was created.
        cost_center:
          type: string
          description: The cost center code associated with this ride.
    CreateConciergeRideRequest:
      type: object
      description: Request body for creating a new concierge ride on behalf of a passenger.
      required:
      - ride_type
      - passenger
      - origin
      - destination
      properties:
        ride_type:
          type: string
          description: Identifier for the type of Lyft ride to request.
        passenger:
          $ref: '#/components/schemas/Passenger'
        origin:
          $ref: '#/components/schemas/Location'
        destination:
          $ref: '#/components/schemas/Location'
        scheduled_pickup_time:
          type: string
          format: date-time
          description: The requested pickup time for a scheduled ride. If omitted, the ride will be dispatched immediately. Must be at least 30 minutes in the future and no more than 7 days ahead.
        notes:
          type: string
          description: Special instructions or notes for the driver, such as building entrance details or patient mobility requirements.
          maxLength: 500
        cost_center:
          type: string
          description: An optional cost center code for billing and reporting purposes.
    ConciergeRideStatus:
      type: object
      description: Real-time status and tracking information for a concierge ride.
      properties:
        ride_id:
          type: string
          description: Unique identifier for the ride.
        status:
          $ref: '#/components/schemas/ConciergeRideStatusEnum'
        driver_location:
          type: object
          description: Current location of the driver, available when a driver has been assigned.
          properties:
            lat:
              type: number
              format: double
              description: Latitude of the driver's current position.
            lng:
              type: number
              format: double
              description: Longitude of the driver's current position.
        eta_seconds:
          type: integer
          description: Estimated time in seconds until the driver arrives at the pickup location.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the status was last updated.
    ConciergeRideStatusEnum:
      type: string
      description: Status of a concierge ride throughout its lifecycle.
      enum:
      - pending
      - scheduled
      - matched
      - arriving
      - pickedUp
      - droppedOff
      - canceled
      - failed
    Passenger:
      type: object
      description: Contact information for the ride passenger. The passenger does not need to have a Lyft account.
      required:
      - first_name
      - phone_number
      properties:
        first_name:
          type: string
          description: First name of the passenger.
        last_name:
          type: string
          description: Last name of the passenger.
        phone_number:
          type: string
          description: Phone number where the passenger can be reached. The passenger will receive ride status notifications via SMS at this number.
        email:
          type: string
          format: email
          description: Email address for the passenger.
  parameters:
    rideId:
      name: id
      in: path
      description: The unique identifier of the concierge ride.
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token obtained through the client credentials flow for the organization's concierge API client.
externalDocs:
  description: Lyft Concierge API Documentation
  url: https://www.lyft.com/developers/products/concierge-api