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

# Search fuel transactions

> Search fuel transactions with paginated POST filters — card, driver, unit, date range, fuel type, and merchant, returning gallons, price, and totals.

The endpoint for searching fuel transactions requires specifying the API version in the URL path. This ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/docs/versioning) page.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body

The following fields are required in the request body to filter the search results:

`<Table align={["left","left","left","left"]}>`

<thead>
  <tr>
    <th>
      Parameter
    </th>

    <th>
      Type
    </th>

    <th>
      Required
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Page
    </td>

    <td>
      Integer
    </td>

    <td>
      No
    </td>

    <td>
      The page number to retrieve.
    </td>
  </tr>

  <tr>
    <td>
      PageSize
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The number of results per page.
      PageSize must be greater than 0.
    </td>
  </tr>

  <tr>
    <td>
      FuelCardNumber
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The fuel card number used for the transactions. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TruckNumber
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The truck number associated with the transactions.This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TransactionRange
    </td>

    <td>
      Object
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The date range for the transactions.
      This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TransactionRange.Start
    </td>

    <td>
      String (Date-Time)
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The start date of the transaction range. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TransactionRange.End
    </td>

    <td>
      String (Date-Time)
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The end date of the transaction range. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>
</tbody>

`</Table>`

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/fuel/search' \
--header 'Authorization: Bearer eP90PNFxr_y74mLOETt0hFmWxz_1VBt_oYx9YuSNUz8....' \
--header 'Content-Type: application/json' \
--data '{ 
  "Page": 0,
  "PageSize": 100,
  "FuelCardNumber": "",
  "TruckNumber": "",
  "TransactionRange": {
     "Start": "2022-07-29T15:33:17.224Z",
     "End": "2025-07-29T15:33:17.224Z"
  }
}'
```

### Response Parameters

The following table lists the parameters included in the response for fuel transaction search requests:

| Parameter                    | Type               | Description                                                      |
| ---------------------------- | ------------------ | ---------------------------------------------------------------- |
| Page                         | Integer            | The current page number of the results.                          |
| PageSize                     | Integer            | The number of results per page.                                  |
| Total                        | Integer            | The total number of matching fuel transactions.                  |
| Items                        | Array of Objects   | The list of fuel transaction records matching the criteria.      |
| Items.Id                     | String             | The unique identifier of the fuel transaction.                   |
| Items.TransactionId          | String             | The transaction ID.                                              |
| Items.SubsidiaryId           | String             | The subsidiary ID associated with the transaction.               |
| Items.SubsidiaryName         | String             | The name of the subsidiary associated with the transaction.      |
| Items.TruckId                | String             | The unique identifier of the truck.                              |
| Items.TruckNumber            | String             | The truck number associated with the transaction.                |
| Items.DriverId               | String             | The unique identifier of the driver.                             |
| Items.DriverName             | String             | The name of the driver.                                          |
| Items.OwnerOperatorId        | String             | The unique identifier of the owner-operator.                     |
| Items.OwnerOperatorName      | String             | The name of the owner-operator.                                  |
| Items.Source                 | String             | The name of the fuel card provider.                              |
| Items.Type                   | String             | The raw fuel type provided by the fuel provider.                 |
| Items.Category               | String             | The internal fuel category (e.g., Diesel, DEF, Cash Advance).    |
| Items.Description            | String             | The fuel product description provided by the fuel card provider. |
| Items.Location               | Object             | The location details of the transaction.                         |
| Items.Location.Id            | String             | The unique identifier of the location.                           |
| Items.Location.Name          | String             | The name of the location.                                        |
| Items.Location.City          | String             | The city of the location.                                        |
| Items.Location.State         | String             | The state of the location.                                       |
| Items.Location.Address       | String             | The address of the location.                                     |
| Items.Location.Country       | String             | The country of the location.                                     |
| Items.FuelTotal              | Object             | The total fuel amount.                                           |
| Items.FuelTotal.Amount       | Number             | The amount of fuel.                                              |
| Items.FuelTotal.Currency     | Integer            | The currency of the fuel amount.                                 |
| Items.Fees                   | Object             | The total fees.                                                  |
| Items.Fees.Amount            | Number             | The amount of fees.                                              |
| Items.Fees.Currency          | Integer            | The currency of the fees amount.                                 |
| Items.Discounts              | Object             | The total discounts.                                             |
| Items.Discounts.Amount       | Number             | The amount of discounts.                                         |
| Items.Discounts.Currency     | Integer            | The currency of the discounts amount.                            |
| Items.Advances               | Object             | The total advances.                                              |
| Items.Advances.Amount        | Number             | The amount of advances.                                          |
| Items.Advances.Currency      | Integer            | The currency of the advances amount.                             |
| Items.Total                  | Object             | The total amount including fuel, fees, discounts, and advances.  |
| Items.Total.Amount           | Number             | The total amount.                                                |
| Items.Total.Currency         | Integer            | The currency of the total amount.                                |
| Items.Quantity               | Object             | Details of the fuel quantity purchased.                          |
| Items.Quantity.Value         | Number             | The numeric value of the fuel purchased.                         |
| Items.Quantity.UnitOfMeasure | String             | The unit of measure (e.g., Gallons).                             |
| Items.TransactionDate        | String (date-time) | The date and time of the fuel transaction.                       |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/docs/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


## OpenAPI

````yaml POST /api/p/v{version}/fuel/search
openapi: 3.0.1
info:
  title: Alvys
  description: >-
    Alvys provides a robust set of REST APIs to allow you to integrate Alvys
    into virtually any platform. These APIs cover most of Alvys' major product
    areas with additional endpoints being added regularly based on customer
    requests.
  contact:
    name: Alvys Support
    url: https://www.alvys.com/resources/contact/
  version: v1
servers:
  - url: https://integrations.alvys.com
    description: Public API Server
  - url: https://api.alvys.com/
    description: Public API Server
security:
  - Public: []
tags:
  - name: Authentication
    description: Obtain an OAuth 2.0 access token for the Alvys Public API.
  - name: Carrier Settlement Statements
    description: >-
      Search carrier settlement statements and retrieve a single statement by
      number.
  - name: Carriers
    description: Read carrier records, search carriers, and manage carrier documents.
  - name: Customers
    description: Create, read, update, delete, and search customer records.
  - name: Deductions
    description: >-
      Create one-time deductions and search or delete existing deduction
      records.
  - name: DispatchPreferences
    description: Dispatch preferences endpoints for reading dispatch rules and preferences.
  - name: Driver Settlement Statements
    description: >-
      Search driver settlement statements and retrieve a single statement by
      number.
  - name: Drivers
    description: >-
      Read driver records, search drivers and driver events, and manage driver
      documents.
  - name: Fuel
    description: Read and search fuel transactions.
  - name: Invoices
    description: >-
      Read invoices, create carrier invoices, and record carrier and customer
      payments.
  - name: Loads
    description: Read, update, search loads, and manage load documents and notes.
  - name: Locations
    description: Read and search company location details.
  - name: Maintenance
    description: Read and search maintenance records.
  - name: Tenders
    description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
  - name: Tolls
    description: Read and search toll transactions.
  - name: Trailers
    description: Read trailers, search trailer events, and manage trailer documents.
  - name: Trips
    description: >-
      Read, search trips, manage trip documents, and record stop appointments,
      arrivals, and departures.
  - name: Trucks
    description: Read trucks, search truck events, and manage truck documents.
  - name: Users
    description: List and search users.
  - name: Visibility
    description: >-
      Read inbound and outbound visibility history and search outbound
      visibility errors.
  - name: Webhooks
    description: >-
      Create, read, update, delete, enable, disable, verify, test, and rotate
      secrets for webhook subscriptions; read event types, delivery logs, and
      health metrics.
paths:
  /api/p/v{version}/fuel/search:
    post:
      tags:
        - Fuel
      summary: Search fuel transactions
      parameters:
        - name: version
          in: path
          description: API version (e.g., 1.0)
          required: true
          schema:
            type: string
            default: '1.0'
            example: '1.0'
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Alvys.Models.Users.FuelSearchRequest'
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Alvys.Models.Users.FuelSearchRequest'
          text/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Alvys.Models.Users.FuelSearchRequest'
          application/*+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Alvys.Models.Users.FuelSearchRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Alvys.Helpers.PagedResponse1Alvys.Models.Trucks.FuelResponse
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
      security:
        - Public: []
components:
  schemas:
    Alvys.Models.Users.FuelSearchRequest:
      required:
        - Page
        - PageSize
      type: object
      properties:
        Page:
          type: integer
          format: int32
        PageSize:
          type: integer
          format: int32
        FuelCardNumber:
          type: string
          nullable: true
        TruckNumber:
          type: string
          nullable: true
        TransactionRange:
          allOf:
            - $ref: '#/components/schemas/Alvys.Models.Period'
          nullable: true
      additionalProperties: false
    Alvys.Helpers.PagedResponse1Alvys.Models.Trucks.FuelResponse:
      required:
        - Items
        - Page
        - PageSize
        - Total
      type: object
      properties:
        Page:
          type: integer
          format: int32
        PageSize:
          type: integer
          format: int32
        Facets:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Alvys.Helpers.ResultSetFacetItem'
          nullable: true
        Total:
          type: integer
          format: int64
        Items:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.Trucks.FuelResponse'
      additionalProperties: false
    Microsoft.AspNetCore.Mvc.ValidationProblemDetails:
      required:
        - Errors
      type: object
      properties:
        Errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Microsoft.AspNetCore.Mvc.ProblemDetails:
      type: object
      properties:
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Alvys.Models.Period:
      required:
        - Start
      type: object
      properties:
        Start:
          type: string
          format: date-time
        End:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    Alvys.Helpers.ResultSetFacetItem:
      required:
        - Count
        - Value
      type: object
      properties:
        Value:
          type: string
        Count:
          type: integer
          format: int64
      additionalProperties: false
    Alvys.Models.Trucks.FuelResponse:
      required:
        - Advances
        - Discounts
        - Fees
        - FuelTotal
        - Id
        - Quantity
        - Source
        - Total
        - TransactionId
      type: object
      properties:
        Id:
          type: string
        TransactionId:
          type: string
        SubsidiaryId:
          type: string
          nullable: true
        SubsidiaryName:
          type: string
          nullable: true
        TruckId:
          type: string
          nullable: true
        TruckNumber:
          type: string
          nullable: true
        DriverId:
          type: string
          nullable: true
        DriverName:
          type: string
          nullable: true
        OwnerOperatorId:
          type: string
          nullable: true
        OwnerOperatorName:
          type: string
          nullable: true
        Source:
          type: string
        Type:
          type: string
          nullable: true
        Category:
          type: string
          nullable: true
        Description:
          type: string
          nullable: true
        Location:
          allOf:
            - $ref: >-
                #/components/schemas/Alvys.Models.Trucks.FuelResponsePumpLocation
          nullable: true
        FuelTotal:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        Fees:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        Discounts:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        Advances:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        Total:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        Quantity:
          allOf:
            - $ref: '#/components/schemas/Alvys.Volume'
        TransactionDate:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    Alvys.Models.Trucks.FuelResponsePumpLocation:
      type: object
      properties:
        Id:
          type: string
          nullable: true
        Name:
          type: string
          nullable: true
        City:
          type: string
          nullable: true
        State:
          type: string
          nullable: true
        Address:
          type: string
          nullable: true
        Country:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Money:
      required:
        - Amount
      type: object
      properties:
        Amount:
          type: number
          format: double
        Currency:
          type: integer
          format: int32
          nullable: true
      additionalProperties: false
    Alvys.Volume:
      required:
        - UnitOfMeasure
        - Value
      type: object
      properties:
        Value:
          type: number
          format: double
        UnitOfMeasure:
          allOf:
            - $ref: '#/components/schemas/Alvys.VolumeVolumeUnits'
      additionalProperties: false
    Alvys.VolumeVolumeUnits:
      enum:
        - Gallons
        - Liters
        - Bushels
        - CubicFoot
        - CubicMeter
        - Quarts
      type: string
  securitySchemes:
    Public:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 client-credentials access token. Obtain one from
        https://auth.alvys.com/oauth/token (grant_type=client_credentials,
        audience=https://api.alvys.com/public/), then paste it here. The
        playground sends it as `Authorization: Bearer <token>`.

````