Lyft Concierge API

openapi: 3.1.0
info:
  title: Lyft Concierge 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
externalDocs:
  description: Lyft Concierge API Documentation
  url: https://www.lyft.com/developers/products/concierge-api
servers:
  - url: https://api.lyft.com/v1
    description: Production Server
tags:
  - name: Concierge Rides
    description: >-
      Endpoints for creating, scheduling, tracking, and managing rides on
      behalf of passengers who may not have a Lyft account.
  - name: Cost Estimates
    description: >-
      Endpoints for estimating ride costs for concierge bookings.
  - name: Ride Types
    description: >-
      Endpoints for retrieving available ride types for concierge bookings.
security:
  - bearerAuth: []
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
  /concierge/ridetypes:
    get:
      operationId: listConciergeRideTypes
      summary: List available concierge ride types
      description: >-
        Returns the ride types available for concierge bookings at the
        specified location. Availability may differ from consumer ride types
        based on the organization's concierge program configuration.
      tags:
        - Ride Types
      parameters:
        - name: lat
          in: query
          description: >-
            Latitude of the pickup location.
          required: true
          schema:
            type: number
            format: double
        - name: lng
          in: query
          description: >-
            Longitude of the pickup location.
          required: true
          schema:
            type: number
            format: double
      responses:
        '200':
          description: Successful response with available ride types
          content:
            application/json:
              schema:
                type: object
                properties:
                  ride_types:
                    type: array
                    description: >-
                      List of ride types available for concierge bookings.
                    items:
                      $ref: '#/components/schemas/ConciergeRideType'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing access token
  /concierge/cost:
    get:
      operationId: listConciergeCostEstimates
      summary: List concierge cost estimates
      description: >-
        Returns estimated costs for concierge rides between two locations.
        Cost estimates reflect the organization's concierge pricing, which
        may differ from consumer pricing.
      tags:
        - Cost Estimates
      parameters:
        - name: start_lat
          in: query
          description: >-
            Latitude of the pickup location.
          required: true
          schema:
            type: number
            format: double
        - name: start_lng
          in: query
          description: >-
            Longitude of the pickup location.
          required: true
          schema:
            type: number
            format: double
        - name: end_lat
          in: query
          description: >-
            Latitude of the destination location.
          required: true
          schema:
            type: number
            format: double
        - name: end_lng
          in: query
          description: >-
            Longitude of the destination location.
          required: true
          schema:
            type: number
            format: double
        - name: ride_type
          in: query
          description: >-
            Filter cost estimates by a specific ride type.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response with cost estimates
          content:
            application/json:
              schema:
                type: object
                properties:
                  cost_estimates:
                    type: array
                    description: >-
                      List of cost estimates for available ride types.
                    items:
                      $ref: '#/components/schemas/ConciergeCostEstimate'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing access token
components:
  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.
  parameters:
    rideId:
      name: id
      in: path
      description: >-
        The unique identifier of the concierge ride.
      required: true
      schema:
        type: string
  schemas:
    ConciergeRideStatusEnum:
      type: string
      description: >-
        Status of a concierge ride throughout its lifecycle.
      enum:
        - pending
        - scheduled
        - matched
        - arriving
        - pickedUp
        - droppedOff
        - canceled
        - failed
    ConciergeRideType:
      type: object
      description: >-
        A ride type available for concierge bookings at a given location.
      properties:
        ride_type:
          type: string
          description: >-
            Identifier for the ride type.
        display_name:
          type: string
          description: >-
            Human-readable name for the ride type.
        seats:
          type: integer
          description: >-
            Maximum number of passenger seats.
        image_url:
          type: string
          format: uri
          description: >-
            URL to an image representing the ride type.
    ConciergeCostEstimate:
      type: object
      description: >-
        Estimated cost for a concierge ride between two locations.
      properties:
        ride_type:
          type: string
          description: >-
            Identifier for the ride type.
        display_name:
          type: string
          description: >-
            Human-readable name for the ride type.
        currency:
          type: string
          description: >-
            ISO 4217 currency code.
          pattern: '^[A-Z]{3}$'
        estimated_cost_cents_min:
          type: integer
          description: >-
            Lower bound of the estimated cost in cents.
        estimated_cost_cents_max:
          type: integer
          description: >-
            Upper bound of the estimated cost in cents.
        estimated_distance_miles:
          type: number
          format: double
          description: >-
            Estimated ride distance in miles.
        estimated_duration_seconds:
          type: integer
          description: >-
            Estimated ride duration in seconds.
    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.
    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.
    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.
    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.
    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.
    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.
    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.