# Lucid ELD Integration API — OpenAPI 3.1 spec
# Auto-generated from src/data/endpoints.ts. Do not hand-edit.
# Last generated: 2026-05-25T20:40:07.831Z

openapi: 3.1.0
info:
  title: Lucid ELD Developer API
  version: 2.0.0
  description: |-
    # Build integrations with Lucid ELD

    Programmatic access to Lucid ELD carrier data: real-time vehicle GPS, driver Hours of Service, historical breadcrumbs, and carrier profile details. REST · JSON · UTF-8 · all timestamps UTC.

    > **The two-key model in one line.** One *Provider Key* identifies you. One *Company Key* identifies the carrier whose data you're requesting. To switch carriers, swap the Company Key — nothing else changes.

    ## Quickstart

    Make your first authenticated call in under 5 minutes.

    ### 1. Get a Provider Key

    Your **Provider Key** identifies your platform. We issue one per integration and it stays the same for every call.

    [**Email us for a Provider Key →**](mailto:office@lucideld.com?subject=Provider%20Key%20Request&body=Hi%20Lucid%20ELD%20team%2C%0A%0AI'd%20like%20to%20request%20a%20Provider%20Key%20to%20build%20an%20integration%20with%20your%20API.%0A%0ACompany%3A%20%0AUse%20case%3A%20%0AContact%20name%3A%20%0A%0AThanks!)

    We'll reply with your Provider Key and a test Company Key you can use to verify your integration end-to-end.

    ### 2. Get your carrier's Company Key

    Each carrier you onboard generates a **Company Key** from their Lucid ELD portal and shares it with you. You put it in your `X-API-Company-Key` header.

    [**View the 4-step Carrier API Key Guide →**](/carrier-key)

    Share that link directly with your carrier customers — it's a self-serve walkthrough designed for them.

    ### 3. Make your first call

    Hit `/v2/company-info` with both keys in the headers. Success means everything is wired up.

    ```bash
    curl -X GET "https://api.lucideld.com/v2/company-info" \
      -H "X-API-Provider-Key: YOUR_PROVIDER_KEY" \
      -H "X-API-Company-Key: CARRIER_COMPANY_KEY"
    ```

    Expected response:

    ```json
    {
      "description": "success",
      "data": {
        "company_name": "APEX FREIGHT LLC",
        "dot_number": "4182937"
      }
    }
    ```

    If you see `"description": "success"` with the carrier's name and DOT number, you're set up. Pick any endpoint from the sidebar to keep going.

    ## Authentication

    Every request requires **both** headers. Neither is optional.

    | Header | Value | Scope |
    | --- | --- | --- |
    | `X-API-Provider-Key` | Your provider key | Identifies your platform. Same for every request. |
    | `X-API-Company-Key` | The carrier's company key | Scopes all data to that carrier only. |

    **One Provider Key, many carriers.** You need only one Provider Key for your entire integration. To access a different carrier's data, swap the Company Key. No other changes.

    **Key format note.** Some older keys have a `system-` prefix. Both formats are accepted. New keys are issued without the prefix.

    **On error:** missing or invalid headers return `401 Unauthorized`:

    ```json
    {
      "status_code": 401,
      "description": "Company API key is not valid",
      "data": null
    }
    ```

    ## Response Format & Pagination

    Every endpoint returns the same JSON envelope:

    | Field | Type | Description |
    | --- | --- | --- |
    | `description` | string | `"success"` or an error message |
    | `data` | object / array / null | The response payload |
    | `page` | integer | Current page (paginated endpoints) |
    | `size` | integer | Items in this page |
    | `total_elements` | integer | Total records available |
    | `total_pages` | integer | Total pages |
    | `next_page_token` | string | Next-page token (location history only) |
    | `status_code` | integer | Present only on error responses |

    Most list endpoints use `page` (1-indexed) and `limit`. Start at `page=1` and increment until `page >= total_pages`. The vehicle location history endpoint uses token-based pagination — pass `next_page_token` from the previous response.

    ## Rate Limiting

    The `X-API-Provider-Key` is rate-limited. The `X-API-Company-Key` is not. Hit a limit? Implement exponential backoff and avoid polling more often than necessary (data freshness in motion is ~60s). Need a higher limit? [Email us](mailto:office@lucideld.com).

    ## Duty Status Codes

    Returned in the `current_status` field of *Latest Driver Status*.

    | Code | Meaning |
    | --- | --- |
    | `DS_D` | Driving |
    | `DS_ON` | On Duty (Not Driving) |
    | `DS_SB` | Sleeper Berth |
    | `DS_OFF` | Off Duty |
    | `DR_IND_PC` | Personal Conveyance |
    | `DR_IND_YM` | Yard Move |

    HOS values are returned in **milliseconds**. Common conversions:

    | Milliseconds | Hours |
    | --- | --- |
    | `28,800,000` | 8 hours |
    | `39,600,000` | 11 hours |
    | `50,400,000` | 14 hours |
    | `252,000,000` | 70 hours |

    ## Migrating from v1

    If you're building a new integration, skip this section.

    **Authentication: bearer token removed.** v1 required POSTing credentials to `/authentication` for a JWT bearer token, then passing `Authorization: Bearer` on every request, with refresh logic. v2 replaces all of that with two static headers. Remove from your codebase: the `/authentication` call, token storage, token refresh logic, and the `Authorization` header.

    **Endpoint URL changes:**

    | v1 | v2 |
    | --- | --- |
    | `POST /authentication` | Removed |
    | `GET /v1/company-info` | `GET /v2/company-info` |
    | `GET /v1/drivers` | `GET /v2/drivers` |
    | `GET /v1/driver/{driverId}` | `GET /v2/driver/{driver_id}` |
    | `GET /v1/latest_driver_status` | `GET /v2/latest-driver-status` |
    | `GET /v1/vehicles` | `GET /v2/vehicles` |
    | `GET /v1/vehicle/{vehicleId}` | `GET /v2/vehicle/{vehicle_id}` |
    | `GET /v1/latest_vehicle_status` | `GET /v2/latest-vehicle-status` |
    | *Not available* | `GET /v2/vehicle-location-history/{vehicle_id}` |

    **Pagination & fields:**

    - `skip + limit` → `page (1-indexed) + limit`. Responses now include `page`, `size`, `total_elements`, `total_pages`.
    - Every parameter and response field renamed from `camelCase` → `snake_case`: `driverId` → `driver_id`, `firstName` → `first_name`, `currentStatus` → `current_status`, `VIN` → `vin`.
    - Entity IDs migrated to UUID. Old-format IDs are still accepted in path parameters but responses always return UUID format. To remap stored IDs, match by `username` (drivers) or `vin` (vehicles).
    - Vehicle status filter values: `All` → omit; `Active` → `active`; `Inactive` → `inactive`.

    ## Support

    Email [office@lucideld.com](mailto:office@lucideld.com) with your Provider Key (or company name) and a description of the endpoint or error you're working with. We typically respond within one business day.

    ## Changelog

    | Date | Changes |
    | --- | --- |
    | May 26, 2026 | Documentation site refresh and organization. |
    | April 1, 2026 | Updated documentation layout for better readability. |
    | February 18, 2026 | Added comprehensive v1 → v2 Migration Reference section. |
    | February 5, 2026 | v1 IDs accepted as input, but responses always return new UUID format. |
    | January 23, 2026 | Initial v2 release. |
  contact:
    name: Lucid ELD Support
    email: office@lucideld.com
    url: https://developer.lucideld.com/
  license:
    name: Lucid ELD API Terms
    url: https://lucideld.com/terms
servers:
  - url: https://api.lucideld.com
    description: Production
security:
  - ProviderKey: []
    CompanyKey: []
tags:
  - name: Company
    description: Carrier profile data. Use this to confirm credentials before doing real work.
  - name: Drivers
    description: Driver roster + Hours of Service. HOS values are milliseconds — divide by 3,600,000 for hours.
  - name: Vehicles
    description: Vehicle roster, real-time location, and up to 6 months of GPS history.
components:
  securitySchemes:
    ProviderKey:
      type: apiKey
      in: header
      name: X-API-Provider-Key
      description: Identifies your platform. Issued by Lucid ELD.
    CompanyKey:
      type: apiKey
      in: header
      name: X-API-Company-Key
      description: Identifies the carrier. Generated by the carrier in their Lucid ELD portal.
paths:
  /v2/company-info:
    get:
      summary: Get Company Info
      description: Returns the carrier's name and DOT number. Use this endpoint to confirm your credentials are working before building out the rest of your integration.
      tags:
        - Company
      operationId: company_info
      responses:
        "200":
          description: Success
          content:
            application/json:
              example:
                description: success
                data:
                  company_name: APEX FREIGHT LLC
                  dot_number: "4182937"
        "401":
          description: Unauthorized — invalid or missing keys
          content:
            application/json:
              example:
                status_code: 401
                description: Company API key is not valid
                data: null
  /v2/drivers:
    get:
      summary: List Drivers
      description: Returns all drivers for the carrier. Paginate through pages to retrieve the complete list — start at page=1 and stop when page >= total_pages.
      tags:
        - Drivers
      operationId: get_drivers
      parameters:
        - name: limit
          in: query
          required: false
          description: Records per page
          schema:
            type: integer
            default: 100
            maximum: 1000
          example: "100"
        - name: page
          in: query
          required: false
          description: Page number (1-indexed)
          schema:
            type: integer
            default: 1
          example: "1"
      responses:
        "200":
          description: Success
          content:
            application/json:
              example:
                description: success
                data:
                  - driver_id: d4f7b2e9-1a3c-4d8f-b5e6-2c9a7d3f1e0b
                    username: jcarter01
                    first_name: James
                    last_name: Carter
                    active: true
                  - driver_id: a9c3e7f2-6b4d-4a1e-c8d5-7f2b9e4a6c1d
                    username: mlopez42
                    first_name: Maria
                    last_name: Lopez
                    active: true
                total_elements: 48
                page: 1
                size: 100
                total_pages: 1
        "401":
          description: Unauthorized — invalid or missing keys
          content:
            application/json:
              example:
                status_code: 401
                description: Company API key is not valid
                data: null
  /v2/driver/{driver_id}:
    get:
      summary: Get Driver by ID
      description: Returns profile information for a single driver.
      tags:
        - Drivers
      operationId: get_driver
      parameters:
        - name: driver_id
          in: path
          required: true
          description: The driver's unique identifier
          schema:
            type: string
            format: uuid
          example: d4f7b2e9-1a3c-4d8f-b5e6-2c9a7d3f1e0b
      responses:
        "200":
          description: Success
          content:
            application/json:
              example:
                description: success
                data:
                  driver_id: d4f7b2e9-1a3c-4d8f-b5e6-2c9a7d3f1e0b
                  username: jcarter01
                  first_name: James
                  last_name: Carter
                  active: true
        "401":
          description: Unauthorized — invalid or missing keys
          content:
            application/json:
              example:
                status_code: 401
                description: Company API key is not valid
                data: null
  /v2/latest-driver-status:
    get:
      summary: Latest Driver Status
      description: Returns current Hours of Service for one or all drivers — remaining milliseconds per HOS bucket plus current duty status code.
      tags:
        - Drivers
      operationId: latest_driver_status
      parameters:
        - name: driver_id
          in: query
          required: false
          description: Filter to one driver. Omit for all.
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          description: Records per page
          schema:
            type: integer
            default: 100
            maximum: 1000
          example: "100"
        - name: page
          in: query
          required: false
          description: Page number
          schema:
            type: integer
            default: 1
          example: "1"
      responses:
        "200":
          description: Success
          content:
            application/json:
              example:
                description: success
                data:
                  - driver_id: d4f7b2e9-1a3c-4d8f-b5e6-2c9a7d3f1e0b
                    username: jcarter01
                    break: 27000000
                    drive: 32400000
                    shift: 41400000
                    cycle: 198000000
                    current_status: DS_D
                total_elements: 48
                page: 1
                size: 100
                total_pages: 1
        "401":
          description: Unauthorized — invalid or missing keys
          content:
            application/json:
              example:
                status_code: 401
                description: Company API key is not valid
                data: null
  /v2/vehicles:
    get:
      summary: List Vehicles
      description: Returns all vehicles in the carrier's fleet.
      tags:
        - Vehicles
      operationId: get_vehicles
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by 'active' or 'inactive'. Omit for all.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Records per page
          schema:
            type: integer
            default: 100
            maximum: 1000
          example: "100"
        - name: page
          in: query
          required: false
          description: Page number
          schema:
            type: integer
            default: 1
          example: "1"
      responses:
        "200":
          description: Success
          content:
            application/json:
              example:
                description: success
                data:
                  - vehicle_id: e5c9f3b1-2d7a-4e8c-a6f3-9b1d4e7c2f5a
                    number: "1042"
                    vin: 1XKYD49X3NJ312847
                    active: true
                  - vehicle_id: a2f8d6c4-7b3e-4a9f-c1d8-4e6b2f9a3c7d
                    number: "2087"
                    vin: 3AKJHHDV5MSLR8523
                    active: true
                total_elements: 31
                page: 1
                size: 100
                total_pages: 1
        "401":
          description: Unauthorized — invalid or missing keys
          content:
            application/json:
              example:
                status_code: 401
                description: Company API key is not valid
                data: null
  /v2/vehicle/{vehicle_id}:
    get:
      summary: Get Vehicle by ID
      description: Returns information for a single vehicle.
      tags:
        - Vehicles
      operationId: get_vehicle
      parameters:
        - name: vehicle_id
          in: path
          required: true
          description: The vehicle's unique identifier
          schema:
            type: string
            format: uuid
          example: e5c9f3b1-2d7a-4e8c-a6f3-9b1d4e7c2f5a
      responses:
        "200":
          description: Success
          content:
            application/json:
              example:
                description: success
                data:
                  vehicle_id: e5c9f3b1-2d7a-4e8c-a6f3-9b1d4e7c2f5a
                  number: "1042"
                  vin: 1XKYD49X3NJ312847
                  active: true
        "401":
          description: Unauthorized — invalid or missing keys
          content:
            application/json:
              example:
                status_code: 401
                description: Company API key is not valid
                data: null
  /v2/latest-vehicle-status:
    get:
      summary: Latest Vehicle Status
      description: Returns the most recent location and motion status for one or all vehicles.
      tags:
        - Vehicles
      operationId: latest_vehicle_status
      parameters:
        - name: vehicle_id
          in: query
          required: false
          description: Filter to one vehicle. Omit for all.
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          description: Records per page
          schema:
            type: integer
            default: 100
            maximum: 200
          example: "100"
        - name: page
          in: query
          required: false
          description: Page number
          schema:
            type: integer
            default: 1
          example: "1"
      responses:
        "200":
          description: Success
          content:
            application/json:
              example:
                description: success
                data:
                  - vehicle_id: e5c9f3b1-2d7a-4e8c-a6f3-9b1d4e7c2f5a
                    number: "1042"
                    odometer: "248371"
                    speed: 62
                    lat: "41.878113"
                    lon: "-87.629799"
                    status: IN_MOTION
                    timestamp: 2026-04-02T14:22:17Z
                total_elements: 31
                page: 1
                size: 100
                total_pages: 1
        "401":
          description: Unauthorized — invalid or missing keys
          content:
            application/json:
              example:
                status_code: 401
                description: Company API key is not valid
                data: null
  /v2/vehicle-location-history/{vehicle_id}:
    get:
      summary: Vehicle Location History
      description: Returns historical GPS breadcrumb data. Data is available for up to the last 6 months. Query any date range within that window; results paginate via token (up to 1,000 records per page).
      tags:
        - Vehicles
      operationId: vehicle_location_history
      parameters:
        - name: vehicle_id
          in: path
          required: true
          description: The vehicle's unique identifier
          schema:
            type: string
            format: uuid
          example: e5c9f3b1-2d7a-4e8c-a6f3-9b1d4e7c2f5a
        - name: start_date
          in: query
          required: true
          description: Format MM-DD-YYYY
          schema:
            type: string
          example: 03-30-2026
        - name: end_date
          in: query
          required: true
          description: Format MM-DD-YYYY
          schema:
            type: string
          example: 04-01-2026
        - name: limit
          in: query
          required: false
          description: Records per page
          schema:
            type: integer
            default: 100
            maximum: 1000
          example: "100"
        - name: next_page_token
          in: query
          required: false
          description: From the previous response
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              example:
                description: success
                data:
                  - id: c3f1a7d9-5e2b-4c8f-a1d4-7b9e3f6a2c0d
                    vehicle_number: "1042"
                    vin: 1XKYD49X3NJ312847
                    lat: "41.253789"
                    lng: "-95.934162"
                    status: IN_MOTION
                    speed: "58"
                    timestamp: 2026-04-01T22:14:33Z
                    calc_location: I-80 W near Omaha, NE
                    direction: "270"
                size: 100
                next_page_token: AE8AAAACAAAAA19oawAAABFQ/7Vn...
        "401":
          description: Unauthorized — invalid or missing keys
          content:
            application/json:
              example:
                status_code: 401
                description: Company API key is not valid
                data: null