> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create trip

> Creates a new trip for the specified business. This endpoint is idempotent using the `external_id` field as the idempotency key.

`distance` is optional when both `google_start_place_id` and `google_end_place_id` are provided (from the [address suggestions](/api-reference/v1/get-address-suggestions) endpoints); the driving distance between them is then computed automatically and the trip's `distance_source` is `COMPUTED`. Providing an explicit `distance` always takes precedence and sets `distance_source` to `MANUAL`. A request with neither a `distance` nor both place IDs returns a 400.

When updating an existing trip via `external_id`, the distance is recomputed only if the place IDs change; if they are unchanged, the existing distance is kept.


## OpenAPI

````yaml post /v1/businesses/{businessId}/mileage/trips
openapi: 3.0.1
info:
  title: API
  version: latest
servers: []
security:
  - BearerAuth: []
tags: []
externalDocs:
  url: /
paths:
  /v1/businesses/{businessId}/mileage/trips:
    post:
      tags: []
      summary: Create trip
      description: >-
        Creates a new trip for the specified business. This endpoint is
        idempotent using the `external_id` field as the idempotency key.
      operationId: business.mileage.trips.post
      parameters:
        - name: businessId
          in: path
          description: The UUID of the business.
          required: true
          schema:
            type: string
            format: uuid
        - name: Content-Type
          in: header
          description: Content-Type must be set to application/json.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTripParams'
      responses:
        '200':
          description: Existing trip with matching external_id was updated.
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ApiTrip'
                required:
                  - data
        '201':
          description: Trip created successfully.
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ApiTrip'
                required:
                  - data
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Business or vehicle not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      deprecated: false
components:
  schemas:
    CreateTripParams:
      type: object
      properties:
        vehicle_id:
          type: string
          format: uuid
          description: The UUID of the vehicle used for this trip.
        external_id:
          type: string
          nullable: true
          description: >-
            An optional external identifier for the trip. If provided and a trip
            with this external_id already exists, the existing trip will be
            updated instead of creating a new one.
        distance:
          type: string
          description: >-
            The distance traveled in miles, as a decimal string. Optional when
            both `google_start_place_id` and `google_end_place_id` are provided;
            the driving distance is then computed automatically. Providing a
            distance always takes precedence and marks the trip distance as
            `MANUAL`.
        trip_date:
          type: string
          format: date
          description: The date of the trip (YYYY-MM-DD).
        purpose:
          $ref: '#/components/schemas/TripPurpose'
          default: UNREVIEWED
          description: The purpose classification of the trip.
        start_address:
          type: string
          nullable: true
          description: The starting address of the trip.
        end_address:
          type: string
          nullable: true
          description: The ending address of the trip.
        google_start_place_id:
          type: string
          nullable: true
          description: >-
            Google Maps place ID of the trip start address, from the address
            suggestion endpoints.
        google_end_place_id:
          type: string
          nullable: true
          description: >-
            Google Maps place ID of the trip end address, from the address
            suggestion endpoints.
        start_latitude:
          type: string
          nullable: true
          description: Latitude of the start address, as a decimal string.
        start_longitude:
          type: string
          nullable: true
          description: Longitude of the start address, as a decimal string.
        end_latitude:
          type: string
          nullable: true
          description: Latitude of the end address, as a decimal string.
        end_longitude:
          type: string
          nullable: true
          description: Longitude of the end address, as a decimal string.
        description:
          type: string
          nullable: true
          description: An optional description or notes about the trip.
      required:
        - vehicle_id
        - trip_date
    ApiTrip:
      type: object
      properties:
        type:
          type: string
          description: Resource type. Value will be `com.layerfi.routers.ApiTrip`.
          example: com.layerfi.routers.ApiTrip
        id:
          type: string
          format: uuid
          description: The unique identifier of the trip.
        vehicle:
          $ref: '#/components/schemas/ApiVehicle'
          description: The vehicle used for this trip.
        external_id:
          type: string
          nullable: true
          description: An optional external identifier for the trip, used for idempotency.
        distance:
          type: string
          description: The distance traveled in miles, as a decimal string.
        distance_source:
          $ref: '#/components/schemas/TripDistanceSource'
          description: How the trip distance was determined.
        trip_date:
          type: string
          format: date
          description: The date of the trip (YYYY-MM-DD).
        purpose:
          $ref: '#/components/schemas/TripPurpose'
          description: The purpose classification of the trip.
        start_address:
          type: string
          nullable: true
          description: The starting address of the trip.
        end_address:
          type: string
          nullable: true
          description: The ending address of the trip.
        google_start_place_id:
          type: string
          nullable: true
          description: >-
            Google Maps place ID of the trip start address, from the address
            suggestion endpoints.
        google_end_place_id:
          type: string
          nullable: true
          description: >-
            Google Maps place ID of the trip end address, from the address
            suggestion endpoints.
        start_latitude:
          type: string
          nullable: true
          description: Latitude of the start address, as a decimal string.
        start_longitude:
          type: string
          nullable: true
          description: Longitude of the start address, as a decimal string.
        end_latitude:
          type: string
          nullable: true
          description: Latitude of the end address, as a decimal string.
        end_longitude:
          type: string
          nullable: true
          description: Longitude of the end address, as a decimal string.
        description:
          type: string
          nullable: true
          description: An optional description or notes about the trip.
        mileage_deduction_rate:
          type: string
          description: >-
            The IRS standard mileage rate in cents per mile applicable for the
            trip date.
        estimated_deduction:
          type: integer
          format: int64
          description: >-
            The estimated tax deduction in cents. Only calculated for BUSINESS
            trips; returns 0 for PERSONAL and UNREVIEWED trips.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the trip was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the trip was last updated.
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the trip was deleted, or null if not deleted.
      required:
        - id
        - vehicle
        - distance
        - distance_source
        - trip_date
        - purpose
        - mileage_deduction_rate
        - estimated_deduction
        - created_at
        - updated_at
    ApiError:
      type: object
      description: An error object returned in API error responses.
      properties:
        type:
          $ref: '#/components/schemas/ApiErrorType'
          description: >-
            A fixed category for the error, helpful for categorizing and
            processing errors.
        description:
          type: string
          description: A human-readable error description.
        error_enum:
          $ref: '#/components/schemas/ApiEnumErrorType'
          description: >-
            A stable, machine-readable identifier for programmatically handling
            specific error conditions. Only present for 4xx client errors—not
            included for 5xx server errors. Use this instead of parsing the
            description field, as enum values remain stable across API versions.
          nullable: true
        meta:
          type: object
          description: Optional additional information about the error.
          nullable: true
      required:
        - type
        - description
    TripPurpose:
      type: string
      enum:
        - UNREVIEWED
        - BUSINESS
        - PERSONAL
      description: >-
        The purpose classification of a trip. UNREVIEWED indicates the trip has
        not been categorized yet, BUSINESS indicates a business-related trip
        eligible for mileage deduction, and PERSONAL indicates a personal trip
        not eligible for deduction.
    ApiVehicle:
      type: object
      properties:
        type:
          type: string
          description: Resource type. Value will be `com.layerfi.routers.ApiVehicle`.
          example: com.layerfi.routers.ApiVehicle
        id:
          type: string
          format: uuid
          description: The unique identifier of the vehicle.
        business_id:
          type: string
          format: uuid
          description: The UUID of the business this vehicle belongs to.
        external_id:
          type: string
          nullable: true
          description: >-
            An optional external identifier for the vehicle, used for
            idempotency.
        make_and_model:
          type: string
          description: The make and model of the vehicle (e.g., 'Toyota Camry').
        year:
          type: integer
          description: The model year of the vehicle.
        license_plate:
          type: string
          nullable: true
          description: The license plate number of the vehicle.
        vin:
          type: string
          nullable: true
          description: The Vehicle Identification Number (VIN).
        description:
          type: string
          nullable: true
          description: An optional description or notes about the vehicle.
        is_primary:
          type: boolean
          description: >-
            Whether this is the primary vehicle for the business. Only one
            vehicle can be primary at a time.
        is_eligible_for_deletion:
          type: boolean
          description: >-
            Whether the vehicle can be deleted. A vehicle cannot be deleted if
            it has trips or is archived.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the vehicle was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the vehicle was last updated.
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the vehicle was archived, or null if not archived.
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the vehicle was deleted, or null if not deleted.
      required:
        - id
        - business_id
        - make_and_model
        - year
        - is_primary
        - is_eligible_for_deletion
        - created_at
        - updated_at
    TripDistanceSource:
      type: string
      enum:
        - MANUAL
        - COMPUTED
      description: >-
        How the trip distance was determined. `MANUAL` means the distance was
        provided explicitly; `COMPUTED` means it was calculated as driving
        distance between `google_start_place_id` and `google_end_place_id`.
    ApiErrorType:
      type: string
      enum:
        - ResourceArchived
        - AuthFailure
        - Plaid
        - Stripe
        - InvalidState
        - ResourceNotFound
        - InvalidParameters
        - JsonSerialization
        - Unknown
        - BadRequest
        - PaginationCursor
        - Conflict
        - LedgerOperationFailed
    ApiEnumErrorType:
      type: string
      description: >-
        Stable enum values for programmatic error handling. Only present in 4xx
        error responses.
      enum:
        - AccessCodeInvalid
        - BalanceSheetDoesNotBalance
        - BalanceSheetMissingAccount
        - BankStatementParserError
        - BillStateError
        - BulkCategorizeFailure
        - BulkMatchFailure
        - BusinessTaskAlreadyCompleted
        - BusinessTaskDeleted
        - CalendlyOAuthError
        - CallBookingError
        - CantUpdateTransactionInCustomerPayout
        - CantUpdateTransactionInVendorPayout
        - CheckPayrollConfigNotFound
        - CheckPayrollServiceNotFound
        - ClerkUserAlreadyExists
        - ConflictingQueryParams
        - CustomAccountAlreadyExists
        - CustomTransactionCsvParsingError
        - CustomTransactionUploadFailure
        - CustomerPayoutInputFormatError
        - DoesNotMatchExistingEntity
        - EmptyBatchRequest
        - ExpenseParserError
        - ExternalAccountBalanceReconciliationError
        - ExternalIdConflict
        - InvalidCategory
        - InvalidEffectiveDate
        - InvalidLedgerOperation
        - InvalidMonthlyAverageRange
        - InvalidMultiPartRequest
        - InvalidPaginationCursor
        - InvalidPayload
        - InvoiceDeleted
        - InvoiceNotFound
        - InvoiceReferenceMismatch
        - InvoiceStateError
        - ManualRateLimit
        - MultipleTagKeyFiltersUnsupported
        - NoCognitoUserFound
        - NoOpeningBalanceFound
        - NotYetReconciled
        - OnePasswordApiError
        - OnePasswordItemNotFound
        - OnePasswordVaultNotFound
        - OpenAICategorizationError
        - PaymentLinkInvalid
        - PayrollStateError
        - PeriodIsClosed
        - PeriodNotClosed
        - PhoneNumberAlreadyRegistered
        - PlaidApiError
        - PlaidConnectionBroken
        - PlaidCreateLinkTokenError
        - PlaidCredentialsNotConfigured
        - PlaidExchangePublicTokenError
        - PlaidGetInstitutionByIdError
        - PlaidGetItemError
        - PlaidInvalidEnvironment
        - PlaidItemAlreadyExists
        - PlaidItemNotFound
        - PlaidProcessorApiError
        - PlaidUnlinkItemError
        - QueryParamFormat
        - QueryParamMissing
        - QuickbooksBrokenConnection
        - QuickbooksConnectionAlreadyExists
        - QuickbooksConnectionAlreadySyncing
        - QuickbooksConnectionMissing
        - QuickbooksConnectionNotActivated
        - QuickbooksInvalidRequest
        - QuickbooksInvalidState
        - QuickbooksNoMatchingAccount
        - QuickbooksNonPostingAccountType
        - QuickbooksNotConfigured
        - QuickbooksOAuthCallbackInvalid
        - QuickbooksOAuthError
        - QuickbooksTokenExpired
        - ResourceArchived
        - ScheduleCNotConfigured
        - SmsNotEnabled
        - SpecifiedBadRequest
        - SpecifiedIdNotFound
        - SplitTransactionError
        - StepEvaluationBadRequest
        - StripeConnectAccountIdNotFound
        - StripeCredentialsNotConfigured
        - StripeGetBalanceForConnectAccountFailure
        - StripeRedirectOrRefreshUrlNotConfigured
        - TagFilterNotFound
        - UnexpectedQueryParam
        - UnitAccountsInUse
        - WrongAnswerType
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````