{
  "openapi": "3.0.0",
  "servers": [
    {
      "description": "Production Server",
      "url": "https://loadtracking.truckertools.com"
    }
  ],
  "info": {
    "description": "The Proactive Driver Verification (PDV) API allows brokers to request driver verification documents\nand track verification status. This API enables you to create verification requests, query existing\nrequests, and receive driver-submitted documents.\n",
    "termsOfService": "https://www.truckertools.com/terms",
    "version": "1.0.0",
    "title": "Proactive Driver Verification",
    "contact": {
      "email": "integrations@truckertools.com"
    },
    "license": {
      "name": "Private",
      "url": "https://api.truckertools.com"
    }
  },
  "security": [
    {
      "OAuth2": []
    }
  ],
  "paths": {
    "/proactive-driver-verification/v1/requests": {
      "get": {
        "summary": "List verification requests",
        "description": "Retrieve a paginated list of driver verification requests with optional filters.",
        "operationId": "listVerificationRequests",
        "parameters": [
          {
            "name": "loadNumber",
            "in": "query",
            "description": "Filter by load number",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "driverPhoneNumber",
            "in": "query",
            "description": "Filter by driver phone number",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 15
            }
          },
          {
            "name": "dispatcherEmail",
            "in": "query",
            "description": "Filter by dispatcher email",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by verification request status",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "hasPing",
                "noPing",
                "completed",
                "incomplete"
              ]
            }
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "Filter by start date (format Y-m-d H:i:s)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-01-01 00:00:00"
            }
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "Filter by end date (format Y-m-d H:i:s)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-12-31 23:59:59"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Number of results per page (default 15, max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 15
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with list of verification requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationRequestListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "post": {
        "summary": "Create a verification request",
        "description": "Create a new driver verification request. The driver will receive a notification to submit the requested document.",
        "operationId": "createVerificationRequest",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateVerificationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Verification request created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created resource",
                "schema": {
                  "type": "string",
                  "example": "https://loadtracking.truckertools.com/proactive-driver-verification/v1/requests/550e8400-e29b-41d4-a716-446655440000"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationRequestResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/proactive-driver-verification/v1/requests/{uuid}": {
      "get": {
        "summary": "Get a verification request",
        "description": "Retrieve a specific driver verification request by UUID.",
        "operationId": "getVerificationRequest",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "Unique identifier of the verification request",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with verification request details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationRequestResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a verification request",
        "description": "Update an existing driver verification request. Only non-expired requests can be updated.",
        "operationId": "updateVerificationRequest",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "Unique identifier of the verification request",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateVerificationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification request updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationRequestResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a verification request",
        "description": "Delete a driver verification request.",
        "operationId": "deleteVerificationRequest",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "Unique identifier of the verification request",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Verification request deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://loadtracking.truckertools.com/oauth/token",
            "scopes": {}
          }
        }
      }
    },
    "schemas": {
      "CreateVerificationRequest": {
        "type": "object",
        "required": [
          "loadNumber",
          "driverPhoneNumber",
          "documentRequested"
        ],
        "properties": {
          "loadNumber": {
            "type": "string",
            "description": "The load number associated with this verification request",
            "maxLength": 100,
            "example": "LOAD-12345"
          },
          "driverPhoneNumber": {
            "type": "string",
            "description": "The driver's phone number",
            "maxLength": 15,
            "example": "+15551234567"
          },
          "documentRequested": {
            "type": "string",
            "description": "The type of document being requested from the driver",
            "enum": [
              "side_of_truck",
              "photograph",
              "empty_trailer",
              "team_drivers"
            ],
            "example": "photograph"
          },
          "dispatcherEmail": {
            "type": "string",
            "format": "email",
            "description": "Email address of the dispatcher to notify",
            "maxLength": 255,
            "example": "dispatcher@example.com"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "UpdateVerificationRequest": {
        "type": "object",
        "properties": {
          "loadNumber": {
            "type": "string",
            "description": "The load number associated with this verification request",
            "maxLength": 100,
            "example": "LOAD-12345"
          },
          "driverPhoneNumber": {
            "type": "string",
            "description": "The driver's phone number",
            "maxLength": 15,
            "example": "+15551234567"
          },
          "documentRequested": {
            "type": "string",
            "description": "The type of document being requested from the driver",
            "enum": [
              "side_of_truck",
              "photograph",
              "empty_trailer",
              "team_drivers"
            ],
            "example": "photograph"
          },
          "dispatcherEmail": {
            "type": "string",
            "format": "email",
            "description": "Email address of the dispatcher to notify",
            "maxLength": 255,
            "example": "dispatcher@example.com"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "Address": {
        "type": "object",
        "description": "Address information",
        "properties": {
          "address": {
            "type": "string",
            "description": "Street address",
            "maxLength": 255,
            "example": "123 Main St"
          },
          "city": {
            "type": "string",
            "description": "City name",
            "maxLength": 100,
            "example": "Chicago"
          },
          "state": {
            "type": "string",
            "description": "State code (2 characters)",
            "minLength": 2,
            "maxLength": 2,
            "example": "IL"
          },
          "country": {
            "type": "string",
            "description": "Country code (2 characters)",
            "minLength": 2,
            "maxLength": 2,
            "example": "US"
          },
          "postalCode": {
            "type": "string",
            "description": "Postal/ZIP code",
            "maxLength": 20,
            "example": "60601"
          }
        }
      },
      "VerificationRequest": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the verification request",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "loadNumber": {
            "type": "string",
            "description": "The load number associated with this verification request",
            "example": "LOAD-12345"
          },
          "driverPhoneNumber": {
            "type": "string",
            "description": "The driver's phone number",
            "example": "+15551234567"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "lat": {
            "type": "number",
            "format": "double",
            "description": "Latitude of the request location",
            "example": 41.8781
          },
          "lon": {
            "type": "number",
            "format": "double",
            "description": "Longitude of the request location",
            "example": -87.6298
          },
          "dispatcherEmail": {
            "type": "string",
            "description": "Email address of the dispatcher",
            "example": "dispatcher@example.com"
          },
          "alerts": {
            "$ref": "#/components/schemas/Alerts"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the request was created",
            "example": "2026-06-01T14:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the request was last updated",
            "example": "2026-06-01T15:45:00Z"
          },
          "response": {
            "$ref": "#/components/schemas/VerificationResponse"
          },
          "documents": {
            "type": "array",
            "description": "List of documents submitted by the driver",
            "items": {
              "$ref": "#/components/schemas/VerificationDocument"
            }
          }
        }
      },
      "Alerts": {
        "type": "object",
        "description": "Security alerts associated with the verification request",
        "properties": {
          "isVoipPhone": {
            "type": "boolean",
            "description": "Indicates if the phone number is a VoIP number",
            "example": false
          },
          "isSpoofed": {
            "type": "boolean",
            "description": "Indicates if the request appears to be spoofed",
            "example": false
          },
          "isCompromised": {
            "type": "boolean",
            "description": "Indicates if the request appears to be compromised",
            "example": false
          },
          "isNonNorthAmerica": {
            "type": "boolean",
            "description": "Indicates if the request originated from outside North America",
            "example": false
          },
          "isIpMasked": {
            "type": "boolean",
            "description": "Indicates if the IP address is masked (VPN/proxy)",
            "example": false
          }
        }
      },
      "VerificationResponse": {
        "type": "object",
        "description": "Driver's response to the verification request",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "lat": {
            "type": "number",
            "format": "double",
            "description": "Latitude where the response was submitted",
            "example": 41.8781
          },
          "lon": {
            "type": "number",
            "format": "double",
            "description": "Longitude where the response was submitted",
            "example": -87.6298
          },
          "distance": {
            "type": "number",
            "format": "double",
            "description": "Distance from the requested location (in localized units)",
            "example": 5.2
          },
          "distanceUnit": {
            "type": "string",
            "description": "Unit of distance measurement",
            "enum": [
              "mi",
              "km"
            ],
            "example": "mi"
          },
          "eta": {
            "type": "string",
            "description": "Estimated time of arrival",
            "example": "2026-06-01T16:00:00Z"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the response was created",
            "example": "2026-06-01T15:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the response was last updated",
            "example": "2026-06-01T15:30:00Z"
          }
        }
      },
      "VerificationDocument": {
        "type": "object",
        "description": "Document submitted by the driver",
        "properties": {
          "documentTypeId": {
            "type": "string",
            "description": "Identifier of the document type",
            "example": "1"
          },
          "documentUrl": {
            "type": "object",
            "description": "Signed URL to access the document",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "description": "Pre-signed URL to download the document",
                "example": "https://s3.amazonaws.com/bucket/document.jpg?signature=..."
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the URL expires",
                "example": "2026-06-01T16:30:00Z"
              }
            }
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the document was uploaded",
            "example": "2026-06-01T15:35:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the document was last updated",
            "example": "2026-06-01T15:35:00Z"
          }
        }
      },
      "VerificationRequestResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/VerificationRequest"
          }
        }
      },
      "VerificationRequestListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VerificationRequest"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "description": "Total number of records",
                "example": 100
              },
              "perPage": {
                "type": "integer",
                "description": "Number of records per page",
                "example": 15
              },
              "currentPage": {
                "type": "integer",
                "description": "Current page number",
                "example": 1
              },
              "lastPage": {
                "type": "integer",
                "description": "Last page number",
                "example": 7
              },
              "from": {
                "type": "integer",
                "description": "Starting record number on current page",
                "example": 1
              },
              "to": {
                "type": "integer",
                "description": "Ending record number on current page",
                "example": 15
              }
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": [
          "statusCode",
          "errors"
        ],
        "properties": {
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code",
            "example": 422
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            }
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": [
          "appName",
          "dateTime",
          "message"
        ],
        "properties": {
          "appName": {
            "type": "string",
            "description": "Name of the application that generated the error",
            "example": "loadtracking-api"
          },
          "dateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the error occurred",
            "example": "2026-06-01T20:12:33Z"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message",
            "example": "should have required property 'loadNumber'"
          },
          "keyword": {
            "type": "string",
            "description": "Type of validation error (only for validation errors)",
            "enum": [
              "required",
              "type",
              "format",
              "maxLength",
              "minLength",
              "invalid"
            ],
            "example": "required"
          },
          "params": {
            "type": "object",
            "description": "Additional parameters about the error (only for validation errors)",
            "properties": {
              "missingProperty": {
                "type": "string",
                "description": "Name of the missing required property",
                "example": "loadNumber"
              },
              "property": {
                "type": "string",
                "description": "Name of the property with the error",
                "example": "driverPhoneNumber"
              }
            }
          }
        }
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "Authentication failed or token is invalid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "statusCode": 401,
              "errors": [
                {
                  "appName": "loadtracking-api",
                  "dateTime": "2026-06-01T20:12:33Z",
                  "message": "Unauthorized"
                }
              ]
            }
          }
        }
      },
      "BadRequestError": {
        "description": "Bad request - the request could not be processed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "statusCode": 400,
              "errors": [
                {
                  "appName": "loadtracking-api",
                  "dateTime": "2026-06-01T20:12:33Z",
                  "message": "No active Proactive Driver Verification subscription"
                }
              ]
            }
          }
        }
      },
      "NotFoundError": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "statusCode": 404,
              "errors": [
                {
                  "appName": "loadtracking-api",
                  "dateTime": "2026-06-01T20:12:33Z",
                  "message": "Resource not found"
                }
              ]
            }
          }
        }
      },
      "ValidationError": {
        "description": "Validation error - one or more fields failed validation",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "statusCode": 422,
              "errors": [
                {
                  "appName": "loadtracking-api",
                  "dateTime": "2026-06-01T20:12:33Z",
                  "keyword": "required",
                  "params": {
                    "missingProperty": "loadNumber"
                  },
                  "message": "should have required property 'loadNumber'"
                }
              ]
            }
          }
        }
      }
    }
  }
}