GenLogs Truck Intelligence API

openapi: 3.1.0
info:
  title: GenLogs API
  version: 1.0.0
  description: 'GenLogs Truck Intelligence API. Ground-truth motor-carrier and shipper data from a nationwide
    roadside sensor network: carrier recommendations by lane, carrier and FMCSA profiles, carrier vetting,
    shipper lanes and facilities, onboarded-carrier contact management, mismatch observations, and alert
    webhooks. Base URL https://api.genlogs.io. Authentication uses an x-api-key header plus a short-lived
    Access-Token obtained from /auth/token; endpoint access is gated by named permissions.'
  contact:
    name: GenLogs
    url: https://docs.genlogs.io
    email: contact@genlogs.io
  x-provenance:
    method: searched
    source: https://docs.genlogs.io (per-endpoint embedded OpenAPI fragments + documented endpoints)
    assembled: '2026-07-19'
    operationIds: some operationIds normalized by API Evangelist where the provider fragments omitted
      them
servers:
- url: https://api.genlogs.io
  description: GenLogs Truck Intelligence API
security:
- ApiKeyAuth: []
  AccessToken: []
tags:
- name: auth
  description: Access-token creation and refresh
- name: carrier
  description: Carrier recommendations, profiles and contacts
- name: carrier-vetting
  description: Carrier verification and vetting rules
- name: shipper
  description: Shipper lanes and facilities
- name: alerts
  description: Detection alerts, mismatch observations and webhooks
paths:
  /auth/token:
    post:
      tags:
      - auth
      summary: Create access and refresh tokens
      description: Create and return new access and refresh tokens for a user based on their email and
        password.
      operationId: createAccessToken
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
          format: email
        description: Email of the user requesting tokens.
      - name: password
        in: query
        required: true
        schema:
          type: string
          format: password
        description: Password of the user requesting tokens.
      responses:
        '200':
          description: Access and refresh tokens created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSchema'
        '401':
          description: Token creation failed because credentials are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '422':
          description: Request validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /carrier/recommendations:
    get:
      parameters:
      - name: accept
        in: header
        required: true
        schema:
          type: string
          default: application/json
        description: Specifies the format of the response.
      - name: Access-Token
        in: header
        required: true
        schema:
          type: string
        description: Access Token for authentication
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
        description: API key for authentication
      - in: query
        name: origin_city
        required: true
        schema:
          type: string
          default: Nashville
        description: Origin city for the recommendation
      - in: query
        name: origin_state
        required: true
        schema:
          type: string
          default: TN
        description: Origin state for the recommendation
      - in: query
        name: destination_city
        required: true
        schema:
          type: string
          default: Dallas
        description: Destination city for the recommendation
      - in: query
        name: destination_state
        required: true
        schema:
          type: string
          default: TX
        description: Destination state for the recommendation
      - default: 50
        in: query
        name: origin_radius
        schema:
          type: number
          default: 50
        description: Search radius around the origin location in miles
      - default: 50
        in: query
        name: destination_radius
        schema:
          type: number
          default: 50
        description: Search radius around the destination location in miles
      - default: 0
        in: query
        name: carrier_score_min
        schema:
          type: float
          default: 0
        description: Minimum carrier score
      - default: 100
        in: query
        name: carrier_score_max
        schema:
          type: float
          default: 1
        description: Maximum carrier score
      - default: None
        in: query
        name: fleet_size_min
        schema:
          type: number
        description: Minimum fleet size
      - default: None
        in: query
        name: fleet_size_max
        schema:
          type: number
        description: Maximum fleet size
      - in: query
        name: carried_cargo
        schema:
          type: string
          default: general goods
        description: Type of cargo carried
      - in: query
        name: equipment_types
        schema:
          type: string
          default: flatbed
        description: Type of equipment used by carriers
      - in: query
        name: preferred_carriers
        schema:
          type: boolean
          default: false
        description: Filter for preferred carriers
      - in: query
        name: real_time
        schema:
          type: boolean
          default: false
        description: Request real-time data if available
      - in: query
        name: auth_months_min
        schema:
          type: number
          default: 1
        description: Minimum number of months a carrier has an active common or contract authority with
          FMCSA
      - in: query
        name: power_only
        schema:
          type: boolean
          default: false
      - in: query
        name: broker_authority
        schema:
          type: boolean
          default: false
      - in: query
        name: is_possible_backhaul
        schema:
          type: boolean
          default: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierResponse'
          description: The JSON response containing recommendations and lane volume
      summary: Get carrier recommendations based on location
      operationId: getCarrierRecommendations
  /carrier/contacts:
    post:
      summary: Get contacts for carriers
      description: Returns the contacts related to a carrier (onboarded, dispatch and FMCSA).
      responses:
        '200':
          description: Contacts found
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        has_dispatch:
                          type: string
                        onboarded_contacts:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              phone:
                                type: string
                              email:
                                type: string
                        dispatch_contact:
                          type: array
                          items:
                            type: object
                            properties:
                              phone:
                                type: string
                              email:
                                type: string
                        fmcsa_contact:
                          type: object
                          properties:
                            name:
                              type: string
                            phone:
                              type: string
                            email:
                              type: string
        '401':
          description: Unauthorized – missing token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden – invalid token or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: searchCarrierContacts
  /onboarded-carrier/contacts:
    post:
      summary: Create an onboarded carrier contact
      description: 'Creates a new onboarded carrier contact for the authenticated customer. Requires a
        valid JWT token and the appropriate permission. The `usdot` value must contain digits only, be
        greater than zero, and be at most 9 digits after normalization.

        '
      tags:
      - Onboarded Carriers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - usdot
              properties:
                usdot:
                  type: string
                  description: 'Carrier USDOT number. Must contain digits only, be greater than zero,
                    and be at most 9 digits. Leading zeroes are normalized before persistence.

                    '
                  minLength: 1
                  maxLength: 9
                  pattern: ^[0-9]+$
                name:
                  type: string
                  nullable: true
                  description: Contact name.
                phone:
                  type: string
                  nullable: true
                  description: Contact phone number.
                email:
                  type: string
                  nullable: true
                  description: Contact email address.
      responses:
        '200':
          description: Contact created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      phone:
                        type: string
                      email:
                        type: string
        '400':
          description: Bad Request – Missing or invalid fields.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '403':
          description: Forbidden – The user lacks required permission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      operationId: createOnboardedCarrierContact
    get:
      summary: Retrieve onboarded carrier contacts
      description: 'Returns a paginated list of onboarded carrier contacts for the authenticated customer.
        Only contacts belonging to the customer identified in the JWT are returned. Requires the external-api-get-onboarded-carrier-contact
        permission.

        '
      tags:
      - Onboarded Carriers
      parameters:
      - name: page
        in: query
        required: false
        description: Page number of results to return.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: page_size
        in: query
        required: false
        description: Number of results per page (max 200).
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: usdot_number
        in: query
        required: false
        description: 'USDOT number(s) to filter by. Supports a single value or a comma-separated list.

          '
        schema:
          type: string
      responses:
        '200':
          description: Onboarded carrier contacts retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: array
                    description: List of onboarded carrier contacts.
                    items:
                      type: object
                      properties:
                        contact_id:
                          type: string
                          format: uuid
                          description: Unique identifier of the onboarded carrier contact.
                        dot_number:
                          type: string
                          description: USDOT number associated with the carrier.
                        customer_id:
                          type: integer
                          description: Identifier of the customer that owns the contact.
                        contact_name:
                          type: string
                          description: Full name of the contact.
                        contact_email:
                          type: string
                          description: Email address of the contact.
                        contact_phone:
                          type: string
                          description: Phone number of the contact.
                        contact_source:
                          type: string
                          description: Source of the onboarded contact record.
                  pagination:
                    type: object
                    description: Pagination metadata.
                    properties:
                      page_size:
                        type: integer
                        description: Number of results per page.
                      current_page:
                        type: integer
                        description: Current page number.
                      total_pages:
                        type: integer
                        description: Total number of available pages.
        '400':
          description: Bad Request – Invalid query parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          description: Unauthorized – Invalid or missing authentication headers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: object
                    properties:
                      message:
                        type: string
                      subcode:
                        type: string
        '403':
          description: Forbidden – User does not have required permission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: string
      operationId: listOnboardedCarrierContacts
  /onboarded-carrier/contacts/{contact_id}:
    patch:
      summary: Update an onboarded carrier contact
      description: 'Updates an existing onboarded carrier contact for the authenticated customer. Requires
        a valid JWT token and the appropriate permission. Only the fields provided in the request body
        will be updated. USDOT updates are not supported by this endpoint; including `usdot` in the PATCH
        body returns Bad Request before any persistence operation.

        '
      tags:
      - Onboarded Carriers
      parameters:
      - name: contact_id
        in: path
        required: true
        description: Unique identifier of the contact to update.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: 'Fields to update. At least one must be provided. `usdot` is not accepted in
                PATCH requests.

                '
              properties:
                name:
                  type: string
                  nullable: true
                  description: Contact name.
                email:
                  type: string
                  nullable: true
                  description: Contact email.
                phone:
                  type: string
                  nullable: true
                  description: Contact phone number.
              minProperties: 1
      responses:
        '200':
          description: Contact updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      phone:
                        type: string
                      email:
                        type: string
        '400':
          description: Bad Request – Missing or invalid fields.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '403':
          description: Forbidden – The user lacks required permission or does not own the contact.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '404':
          description: Contact not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      operationId: updateOnboardedCarrierContact
    delete:
      summary: Delete an onboarded carrier contact
      description: 'Deletes an existing onboarded carrier contact for the authenticated customer. Requires
        a valid JWT token and the appropriate permission. The contact must belong to the authenticated
        customer.

        '
      tags:
      - Onboarded Carriers
      parameters:
      - name: contact_id
        in: path
        required: true
        description: Unique identifier of the contact to delete.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Contact deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      deleted:
                        type: boolean
        '400':
          description: Bad Request – Invalid contact identifier.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '403':
          description: 'Forbidden – The user lacks required permission or does not own the contact.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '404':
          description: Contact not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      operationId: deleteOnboardedCarrierContact
  /onboarded-carrier/bulk/contacts:
    post:
      summary: Bulk create onboarded carrier contacts
      description: 'Creates multiple onboarded carrier contacts for the authenticated customer in a single
        request. Each contact entry is validated using the same rules as the single-contact create flow.
        At least one contact must be valid for the operation to succeed. The operation follows the same
        authorization, repository, caching, and creation logic as the single-contact create flow. Each
        `usdot` value must contain digits only, be greater than zero, and be at most 9 digits after normalization.

        '
      tags:
      - Onboarded Carriers
      requestBody:
        required: true
        description: 'List of onboarded carrier contact definitions to create. The contacts array must
          be non-empty.

          '
        content:
          application/json:
            schema:
              type: object
              required:
              - contacts
              properties:
                contacts:
                  type: array
                  minItems: 1
                  description: List of contacts to create.
                  items:
                    type: object
                    required:
                    - usdot
                    properties:
                      usdot:
                        type: string
                        description: 'Carrier USDOT number. Must contain digits only, be greater than
                          zero, and be at most 9 digits. Leading zeroes are normalized before persistence.

                          '
                        minLength: 1
                        maxLength: 9
                        pattern: ^[0-9]+$
                      name:
                        type: string
                        nullable: true
                        description: Contact name.
                      phone:
                        type: string
                        nullable: true
                        description: Contact phone number.
                      email:
                        type: string
                        nullable: true
                        description: Contact email address.
      responses:
        '200':
          description: Contacts processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  created_contacts:
                    type: array
                    description: List of successfully created contacts.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        usdot:
                          type: string
                        name:
                          type: string
                  failed_contacts:
                    type: array
                    description: Per-item errors for contacts that were not created.
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: Index of the contact in the original payload.
                        error:
                          type: string
                          description: Human-readable error message for this item.
        '400':
          description: Bad Request – Invalid request body or all items failed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '403':
          description: Forbidden – Missing required permission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      operationId: createOnboardedCarrierContactsBulk
    delete:
      summary: Bulk delete onboarded carrier contacts
      description: 'Deletes multiple onboarded carrier contacts for the authenticated customer in a single
        request. All provided contact IDs must exist and belong to the authenticated customer. The operation
        follows the same authorization, repository, caching, and deletion logic as the single-contact
        delete flow.

        '
      tags:
      - Onboarded Carriers
      requestBody:
        required: true
        description: 'List of onboarded carrier contact identifiers to delete. At least one contact_id
          must be provided.

          '
        content:
          application/json:
            schema:
              type: object
              required:
              - contact_ids
              properties:
                contact_ids:
                  type: array
                  minItems: 1
                  description: List of contact UUIDs to delete.
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Contacts deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: array
                    description: List of deleted contacts.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        deleted:
                          type: boolean
        '400':
          description: Bad Request – Invalid request body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '403':
          description: Forbidden – Missing required permission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '404':
          description: One or more contacts not found or not owned by the customer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      operationId: deleteOnboardedCarrierContactsBulk
  /compliance-rules:
    get:
      summary: Get carrier compliance rules by USDOT (single or batch)
      description: "Returns carrier compliance rules for one or more USDOT numbers.\n- Single mode: provide\
        \ `usdot_number`. The response shape is a single\n  object with `rules` and `rule_status` and\
        \ is fully backward compatible\n  with the existing API.\n- Batch mode: provide `usdot_numbers`\
        \ as a comma-separated list. The\n  response shape is an object with a `results` array where each\
        \ item\n  represents one USDOT and includes a `found` flag.\n\nWhen both `usdot_number` and `usdot_numbers`\
        \ are provided, `usdot_numbers` takes precedence and `usdot_number` is ignored.\nThe maximum number\
        \ of USDOT values allowed in `usdot_numbers` is limited to 50. Requests that exceed this limit\
        \ return HTTP 400.\nEach batch result item uses `found=false` when no vetting data exists for\
        \ that USDOT. In that case the item only contains `usdot_number` and `found`. When `found=true`,\
        \ `rules` and `rule_status` are populated with the same structure as the single-USDOT response.\n\
        Examples:\n- Single:\n  `/compliance-rules?usdot_number=1234567`\n- Batch:\n  `/compliance-rules?usdot_numbers=1234567,7654321`\n"
      tags:
      - Compliance Rules
      parameters:
      - name: usdot_number
        in: query
        required: false
        description: 'Single USDOT number to evaluate. Ignored when `usdot_numbers` is also provided.

          '
        schema:
          type: string
      - name: usdot_numbers
        in: query
        required: false
        description: 'Comma-separated list of USDOT numbers for batch evaluation. When provided, this
          parameter takes precedence over `usdot_number`.

          '
        schema:
          type: string
      responses:
        '200':
          description: 'Compliance rules retrieved successfully (single or batch).

            - Single: single carrier response (rules + rule_status). - Batch: list of per-carrier results
            with `found` flags.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CarrierRulesSingleResponse'
                - $ref: '#/components/schemas/CarrierRulesBatchResponse'
        '400':
          description: 'Bad Request – invalid input, missing required query parameters, or exceeding the
            maximum allowed nu

# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/genlogs/refs/heads/main/openapi/genlogs-openapi.yml