openapi: 3.1.0
info:
  title: ODFL Document API
  summary: Retrieval of shipment PDF documents from Old Dominion Freight Line.
  description: >-
    The Old Dominion Freight Line Document API retrieves PDF documents
    associated with shipments, including bills of lading and delivery
    receipts, by PRO number. The service is used to programmatically pull
    shipment documentation from ODFL into shipper or partner systems.
  version: '1.0'
  contact:
    name: ODFL API Support
    email: api@odfl.com
    url: https://www.odfl.com/us/en/resources/shipping-api-integrations.html
externalDocs:
  description: ODFL Document API Development Guide
  url: https://www.odfl.com/content/dam/odfl/us/en/documents/web-services/Document%20API%20Development%20Guide.pdf
servers:
  - url: https://www.odfl.com/wsDocument/v1
    description: Old Dominion Freight Line Document API
tags:
  - name: Documents
    description: Retrieve PDF shipping documents associated with ODFL PRO numbers.
paths:
  /documents/{proNumber}:
    get:
      tags:
        - Documents
      summary: Retrieve documents for a PRO number
      description: >-
        Returns the available PDF documents (bill of lading, delivery
        receipt) associated with the supplied ODFL PRO number.
      operationId: getDocumentsByPro
      parameters:
        - name: proNumber
          in: path
          required: true
          schema:
            type: string
          description: ODFL PRO number identifying the shipment.
        - name: documentType
          in: query
          required: false
          schema:
            type: string
            enum:
              - BOL
              - DELIVERY_RECEIPT
              - INVOICE
          description: Optional filter to retrieve a specific document type.
      responses:
        '200':
          description: PDF document(s) successfully returned.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '404':
          description: PRO number or document not found.
        '401':
          description: Authentication failed.
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
  schemas:
    DocumentResponse:
      type: object
      properties:
        proNumber:
          type: string
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    Document:
      type: object
      properties:
        type:
          type: string
        url:
          type: string
          format: uri
        contentBase64:
          type: string
          format: byte
security:
  - BasicAuth: []