> ## 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 deductions
> Search driver deductions with paginated POST filters — driver, deduction type, frequency, effective date range, and active or inactive status.
This endpoint provides detailed information about each deduction that matches the specified search criteria, enabling efficient management and retrieval of deduction records.
Deductions are asset-specific financial adjustments and can be associated with either a driver or a truck, but not both simultaneously.
***
### Request Body Parameters
The following parameters are accepted in the request body:
| Parameter | Type | Required | Description |
| --------------- | ------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page | Integer | Yes | The page number to retrieve. Default is `0`. |
| PageSize | Integer | Yes | The number of items per page. Must be greater than 0. |
| DateRange | Object | Conditionally | The date range to filter by. This field is required if the other conditionally required fields are left empty. |
| DateRange.Start | String (Date-Time) | Yes | Start of the date range (UTC). Required when `DateRange` is supplied. |
| DateRange.End | String (Date-Time) | No | End of the date range (UTC). |
| DriverId | String | Conditionally | Required when filtering by driver. Must not be provided together with TruckId. This field is required if the other conditionally required fields are left empty. |
| TruckId | String | Conditionally | Required when filtering by truck. Must not be provided together with DriverId. This field is required if the other conditionally required fields are left empty. |
| OwnerOperatorId | String | Conditionally | Optional — used only to filter by the current owner of the asset (Driver or Truck). This field is required if the other conditionally required fields are left empty. |
| IncludePaid | Boolean | Yes | When `true`, includes already paid deductions. Default: `false`. |
### Example CURL Request
```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/deductions/search' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"Page": 0,
"PageSize": 100,
"DateRange": {
"Start": "2025-10-07T00:00:00Z",
"End": "2025-10-09T23:59:59Z"
},
"DriverId": "DR2517534557938191",
"OwnerOperatorId": "DR251652563453445290",
"IncludePaid": true
}'
```
***
### Response Body Parameters
The following parameters are included in the response body:
| Parameter | Type | Required | Description |
| ------------------------ | ------------------ | ------------- | --------------------------------------------------------------- |
| Page | Integer | No | The current page of the response. |
| PageSize | Integer | Yes | The number of items per page. |
| Total | Integer | Yes | The total number of deduction records matching the criteria. |
| Items\[] | Array | Yes | The list of deduction records. |
| Items\[].Id | String | Yes | The unique identifier of the deduction. |
| Items\[].Type | String | Yes | Type of record (`"Deduction"`). |
| Items\[].GroupId | String | Yes | Group ID if the deduction belongs to a recurring group or rule. |
| Items\[].Description | String | Yes | Description of the deduction. |
| Items\[].Category | String | Yes | Deduction category (e.g., Fuel, Advance, Drug Test). |
| Items\[].Amount.Amount | Number | Yes | Deduction amount (negative for deductions). |
| Items\[].Amount.Currency | Integer | Yes | ISO numeric currency code (e.g., 840 for USD). |
| Items\[].DriverId | String | Conditionally | The Driver ID linked to the deduction. |
| Items\[].TruckId | String | Conditionally | The Truck ID linked to the deduction. |
| Items\[].OwnerOperatorId | String | No | The Owner Operator ID of truck or driver. |
| Items\[].Date | String (Date) | Yes | The effective date of the deduction (date only, without time). |
| Items\[].IsPaid | Boolean | No | Indicates whether the deduction has been paid. |
| Items\[].CreatedAt | String (Date-Time) | No | Timestamp when the deduction was created (UTC). |
| Items\[].CreatedBy | String | No | Client ID or User ID of the person who created the deduction. |
***
### Example Response
```json theme={null}
{
"Page": 0,
"PageSize": 100,
"Total": 1,
"Items": [
{
"Id": "00000000-dd44-0000-0000-8a1fa91b607a",
"Type": "Deduction",
"GroupId": "344571de-57b4-4163-a0cc-d7981fa65994",
"Description": "Drug Test Detais",
"Category": "Drug Test",
"Amount": {
"Amount": -50,
"Currency": 840
},
"DriverId": "DR2517534557938191",
"OwnerOperatorId": "DR25165000003445290",
"Date": "2025-10-07",
"IsPaid": false,
"CreatedAt": "2025-10-09T08:30:54.873Z",
"CreatedBy": "MhAeS5345435fbvccvbfUdTdXOMgVSGyp"
}
]
}
```
***
### Versioning
The `version` parameter in the URL path specifies which version of the API you are using.
Including the version number ensures that your integration remains stable as the API evolves.
For more details, refer to the [Versioning](/docs/versioning) page.
***
### Rate Limits
All endpoints are subject to standard rate limits to ensure consistent API performance.
For details, see the [Rate Limits](/docs/rate-limits) section.
## OpenAPI
````yaml POST /api/p/v{version}/deductions/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}/deductions/search:
post:
tags:
- Deductions
summary: Search deductions
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.Deductions.DeductionSearchRequest
application/json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Deductions.DeductionSearchRequest
text/json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Deductions.DeductionSearchRequest
application/*+json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Deductions.DeductionSearchRequest
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/Alvys.Helpers.PagedResponse1Alvys.Models.Deductions.DeductionResponse
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
'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.Deductions.DeductionSearchRequest:
required:
- IncludePaid
- Page
- PageSize
type: object
properties:
Page:
type: integer
format: int32
PageSize:
type: integer
format: int32
DateRange:
allOf:
- $ref: '#/components/schemas/Alvys.Models.Period'
nullable: true
DriverId:
type: string
nullable: true
TruckId:
type: string
nullable: true
OwnerOperatorId:
type: string
nullable: true
IncludePaid:
type: boolean
additionalProperties: false
Alvys.Helpers.PagedResponse1Alvys.Models.Deductions.DeductionResponse:
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.Deductions.DeductionResponse'
additionalProperties: false
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.Deductions.DeductionResponse:
required:
- Amount
- Category
- CreatedAt
- Date
- Description
- GroupId
- Id
- IsPaid
- Type
type: object
properties:
Id:
type: string
Type:
type: string
GroupId:
type: string
Description:
type: string
Category:
type: string
Amount:
allOf:
- $ref: '#/components/schemas/Alvys.Money'
DriverId:
type: string
nullable: true
TruckId:
type: string
nullable: true
OwnerOperatorId:
type: string
nullable: true
Date:
type: string
format: date-time
IsPaid:
type: boolean
CreatedAt:
type: string
format: date-time
CreatedBy:
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
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 `.
````