# Alvys: English API Documentation v1.0 API Reference ## API Reference ### Getting Started - [Authentication reference](https://docs.alvys.com/en/api/reference/authentication.md): API reference for OAuth 2.0 Client Credentials authentication on the Alvys Public API — token endpoints, client app setup, and available scopes. - [Get an access token](https://docs.alvys.com/en/api/reference/token.md): Exchange your client credentials for an access token using the OAuth 2.0 Client Credentials flow. ### Carriers - [List carrier documents](https://docs.alvys.com/en/api/reference/carriers/list-carrier-documents.md): List all uploaded documents attached to a specific carrier by carrier ID, including contracts, W-9s, insurance certificates, and operating authority filings. - [Get carrier](https://docs.alvys.com/en/api/reference/carriers/get-carrier.md): Retrieve a single carrier record by ID from Alvys, including MC and DOT numbers, contact details, insurance, safety data, and payment terms. - [Upload carrier document](https://docs.alvys.com/en/api/reference/carriers/upload-carrier-document.md): Upload multipart/form-data. One file per request. Max file size 10 MB. Allowed document types: Carrier Agreement, Carrier Application, Carrier Authority, Carrier Onboarding, Other Documents. Allowed MIME types: application/pdf, image/jpeg, image/png. - [Search carriers](https://docs.alvys.com/en/api/reference/carriers/search-carriers.md): Search Alvys carriers with paginated POST filters — MC and DOT number, name, status, insurance expiration, safety rating, and lane preferences. - [Set carrier status](https://docs.alvys.com/en/api/reference/carriers/set-carrier-status.md): Update a carrier or subsidiary status in Alvys by carrier ID via the Public API, transitioning between active, inactive, blocked, and pending states. - [Search carrier settlement statements](https://docs.alvys.com/en/api/reference/carriers/search-carrier-settlement-statements.md): Search finalized carrier settlement statements in Alvys with paginated POST filters by date range, carrier, statement number, and amount. - [Get carrier settlement statement](https://docs.alvys.com/en/api/reference/carriers/get-carrier-settlement-statement.md): Retrieve a finalized carrier settlement statement from Alvys by statement number, including per-trip breakdown, line items, payments, and totals. ### Customers - [List customers](https://docs.alvys.com/en/api/reference/customers/list-customers.md): List customer records in your Alvys tenant with pagination, returning company profiles, billing addresses, credit terms, and default rate agreements. - [Create customer](https://docs.alvys.com/en/api/reference/customers/create-customer.md): Create a new customer record in Alvys with company profile, billing address, contacts, credit terms, and default rate agreements for future loads. - [Search customers](https://docs.alvys.com/en/api/reference/customers/search-customers.md): Search Alvys customers with paginated POST filters — name, status, billing city and state, credit terms, sales rep, and default rate agreements. - [Update customer](https://docs.alvys.com/en/api/reference/customers/update-customer.md): Partially update a customer record by ID in Alvys, changing only the supplied fields such as billing address, credit terms, contacts, or default rates. - [Delete customer](https://docs.alvys.com/en/api/reference/customers/delete-customer.md): Delete a customer record by ID from your Alvys tenant using the Public API, permanently removing the customer profile, contacts, and associated metadata. ### Deductions - [Get deduction](https://docs.alvys.com/en/api/reference/deductions/get-deduction.md): Retrieve a single driver deduction record by ID, including deduction type, amount, frequency, effective dates, and the driver settlement it applies to. - [Create one-time deduction](https://docs.alvys.com/en/api/reference/deductions/create-one-time-deduction.md): Create a one-time driver deduction that applies to a single upcoming settlement, specifying the driver, amount, deduction type, and effective date. - [Search deductions](https://docs.alvys.com/en/api/reference/deductions/search-deductions.md): Search driver deductions with paginated POST filters — driver, deduction type, frequency, effective date range, and active or inactive status. - [Delete deduction](https://docs.alvys.com/en/api/reference/deductions/delete-deduction.md): Delete a driver deduction record by ID through the Alvys Public API, removing the deduction from payroll settlements and future driver pay statements. ### Dispatch Preferences - [Search dispatch preferences](https://docs.alvys.com/en/api/reference/dispatch-preferences/search-dispatch-preferences.md): Search dispatch preferences with paginated POST filters, returning the routing, equipment, home-time, and lane preferences configured for drivers. ### Drivers - [List drivers](https://docs.alvys.com/en/api/reference/drivers/list-drivers.md): List drivers in your Alvys tenant with pagination, returning employment status, home terminal, license class, current truck assignment, and contact details. - [List driver documents](https://docs.alvys.com/en/api/reference/drivers/list-driver-documents.md): List all documents on file for a driver by driver ID, including CDLs, medical cards, drug test results, hire packets, and other compliance uploads. - [Get driver](https://docs.alvys.com/en/api/reference/drivers/get-driver.md): Retrieve a single driver record by ID from Alvys, including license details, contact info, pay setup, home terminal, and current employment status. - [Upload driver document](https://docs.alvys.com/en/api/reference/drivers/upload-driver-document.md): Upload multipart/form-data. One file per request. Max file size 10 MB. Allowed document types: License, Medical, Driver License, Driver Sheet, Drug Test, Operating Authority, Completed W9 Tax Form (W9 Form), Other Documents. Allowed MIME types: application/pdf, image/jpeg, image/png. - [Search driver events](https://docs.alvys.com/en/api/reference/drivers/search-driver-events.md): Search driver duty and location events with paginated POST filters — driver, event type, date range, and load or trip context for HOS and telematics data. - [Search drivers](https://docs.alvys.com/en/api/reference/drivers/search-drivers.md): Search Alvys drivers with paginated POST filters — name, status, home terminal, license class, hire date range, current truck, and pay setup. - [Search driver settlement statements](https://docs.alvys.com/en/api/reference/drivers/search-driver-settlement-statements.md): Search finalized driver settlement statements in Alvys with paginated POST filters by date range, driver, driver type, and statement number. - [Get driver settlement statement](https://docs.alvys.com/en/api/reference/drivers/get-driver-settlement-statement.md): Retrieve a finalized driver settlement statement from Alvys by statement number, including per-trip breakdown, line items, deductions, and net pay. ### Fuel - [Get fuel transaction](https://docs.alvys.com/en/api/reference/fuel/get-fuel-transaction.md): Retrieve a single fuel transaction by ID from Alvys, including card number, driver, unit, gallons, price per gallon, location, and posted totals. - [Search fuel transactions](https://docs.alvys.com/en/api/reference/fuel/search-fuel-transactions.md): Search fuel transactions with paginated POST filters — card, driver, unit, date range, fuel type, and merchant, returning gallons, price, and totals. ### Invoices - [Get invoice](https://docs.alvys.com/en/api/reference/invoices/get-invoice.md): Retrieve invoice records from Alvys by invoice number or reference, including carrier and customer invoices, line items, aging status, and payment history. - [Create carrier invoice](https://docs.alvys.com/en/api/reference/invoices/create-carrier-invoice.md): Create a carrier invoice in Alvys for a completed load, including line items, accessorials, deductions, and the total amount owed to the carrier. - [Record carrier payment](https://docs.alvys.com/en/api/reference/invoices/record-carrier-payment.md): Record a carrier payment against a trip. Idempotent on `ReferenceNumber` — re-submitting the same reference returns the current state without creating a duplicate payment. - [Record customer payment](https://docs.alvys.com/en/api/reference/invoices/record-customer-payment.md): Record a customer payment against one or more customer invoices in Alvys, including check or ACH reference, amount, deposit date, and payment terms. - [Record invoice financing](https://docs.alvys.com/en/api/reference/invoices/record-invoice-financing.md): Record a factoring or invoice financing event in Alvys for one or more carrier invoices, including funder, funded amount, reserve, and remittance details. - [Search invoices](https://docs.alvys.com/en/api/reference/invoices/search-invoices.md): Search invoices with paginated POST filters — invoice type, customer, carrier, invoice number, status, aging bucket, and issued or paid date range. ### Loads - [Get load](https://docs.alvys.com/en/api/reference/loads/get-load.md): Retrieve load records from Alvys by load number, including customer, rate, stops, assigned driver and truck, current status, and reference numbers. - [Get equipment types](https://docs.alvys.com/en/api/reference/loads/get-equipment-types.md): Returns every equipment type accepted by the Equipment Type field on load create, as an alphabetically ordered array of strings. - [List load documents](https://docs.alvys.com/en/api/reference/loads/list-load-documents.md): List all documents attached to a load by load number, including rate confirmations, BOLs, PODs, lumper receipts, and any customer-required paperwork. - [List load notes](https://docs.alvys.com/en/api/reference/loads/list-load-notes.md): List all internal notes and comments attached to a load by load number, ordered by timestamp with the author and note type for each entry. - [Upload load document](https://docs.alvys.com/en/api/reference/loads/upload-load-document.md): Upload multipart/form-data. One file per request. Max file size 10 MB. Allowed document types: Customer Rate and Load Confirmation, Customer Load Confirmation, Customer Rate Confirmation, Signed Customer Rate Confirmation, Proof of Delivery, Proof of Pickup, Bill of Lading, Shipping Labels. Allowed… - [Change load document type](https://docs.alvys.com/en/api/reference/loads/change-load-document-type.md): Change the document type of a file already attached to a load, for example after classifying an upload that arrived without the right type. - [Create load note](https://docs.alvys.com/en/api/reference/loads/create-load-note.md): Add an internal note or comment to a load by load number, with note type and body, so dispatch and operations can log context on the load timeline. - [Create load reference](https://docs.alvys.com/en/api/reference/loads/create-load-reference.md): Create a custom reference on an existing load by load number, optionally tied to a tenant catalog definition, with values up to 40 characters. - [Update load reference](https://docs.alvys.com/en/api/reference/loads/update-load-reference.md): Update an existing custom reference on a load by load number and reference instance id, requiring If-Match with the current load ETag. - [Search loads](https://docs.alvys.com/en/api/reference/loads/search-loads.md): Search loads with paginated POST filters — customer, status, pickup and delivery date ranges, origin and destination, equipment, and reference numbers. - [Update load](https://docs.alvys.com/en/api/reference/loads/update-load.md): Partially update a load by load number in Alvys, changing only the supplied fields such as rate, references, equipment, assigned driver, or stop details. - [Delete load note](https://docs.alvys.com/en/api/reference/loads/delete-load-note.md): Delete a specific note attached to a load by note ID and load number, permanently removing the comment from the load timeline and operational history. ### Locations - [Get location](https://docs.alvys.com/en/api/reference/locations/get-location.md): Retrieve saved location records from Alvys, including shipper and consignee addresses, contact details, receiving hours, and geocoded coordinates. - [Search locations](https://docs.alvys.com/en/api/reference/locations/search-locations.md): Search saved shipper and consignee locations with paginated POST filters — name, city, state, zip, hours of operation, and appointment requirements. ### Maintenance - [Get maintenance record](https://docs.alvys.com/en/api/reference/maintenance/get-maintenance-record.md): Retrieve a single maintenance record by ID, including the truck or trailer, work order details, vendor, parts, labor cost, and completion date. - [Search maintenance records](https://docs.alvys.com/en/api/reference/maintenance/search-maintenance-records.md): Search maintenance records with paginated POST filters — truck or trailer, work order type, vendor, service date range, and completion status. ### References - [List reference definitions](https://docs.alvys.com/en/api/reference/references/list-reference-definitions.md): Returns tenant custom reference definitions visible to the Public API, keyed by entity (`Load`, `Stop`, …). Pass one or more `entities` query values. Each requested entity requires its matching read scope (`load:read` for `Load`, `stop:read` for `Stop`); requesting both requires both scopes. ### Tenders - [Get tender](https://docs.alvys.com/en/api/reference/tenders/get-tender.md): Retrieve a single tender by tender ID from Alvys, including customer, offered rate, stops, equipment requirements, and current acceptance status. - [Create tender](https://docs.alvys.com/en/api/reference/tenders/create-tender.md): Create a new inbound tender in Alvys from an EDI 204 or manual offer, including customer, stops, offered rate, equipment, and reference numbers. - [Cancel tenders](https://docs.alvys.com/en/api/reference/tenders/cancel-tenders.md): Cancel one or more tenders in bulk by tender ID, sending an EDI 990-style cancellation to the customer for shipments that will not be picked up. - [Search tenders](https://docs.alvys.com/en/api/reference/tenders/search-tenders.md): Search tenders with paginated POST filters — customer, status, offered rate range, pickup and delivery windows, origin and destination, and equipment type. - [Accept tender](https://docs.alvys.com/en/api/reference/tenders/accept-tender.md): Accept an inbound tender by tender ID, converting it into a booked load in Alvys with the customer, rate, stops, and equipment from the offer. - [Accept tender cancellation](https://docs.alvys.com/en/api/reference/tenders/accept-tender-cancellation.md): Acknowledge and accept a customer-initiated tender cancellation by tender ID, confirming the shipment will be released and no longer executed. - [Accept tender updates](https://docs.alvys.com/en/api/reference/tenders/accept-tender-updates.md): Accept customer-initiated updates to an existing tender by tender ID, confirming revised stops, timing, rate, or references against the current tender. - [Reject tender](https://docs.alvys.com/en/api/reference/tenders/reject-tender.md): Reject an inbound tender by tender ID with a reason code, sending an EDI 990-style decline back to the customer so they can retender the shipment. - [Update tender](https://docs.alvys.com/en/api/reference/tenders/update-tender.md): Update one or more open tenders with revised stops, appointment windows, rate, or reference numbers, keeping Alvys in sync with EDI 204 updates. ### Tolls - [Get toll transaction](https://docs.alvys.com/en/api/reference/tolls/get-toll-transaction.md): Retrieve a single toll transaction by ID, including transponder, driver, unit, plaza, timestamp, amount, and the trip or load the toll is tied to. - [Search toll transactions](https://docs.alvys.com/en/api/reference/tolls/search-toll-transactions.md): Search toll transactions with paginated POST filters — transponder, driver, unit, plaza, date range, and amount, returning per-transaction detail. ### Trailers - [List trailers](https://docs.alvys.com/en/api/reference/trailers/list-trailers.md): List trailers in your Alvys fleet with pagination, returning trailer number, type, ownership, license, current status, and last known location. - [Get trailer](https://docs.alvys.com/en/api/reference/trailers/get-trailer.md): Retrieve a single trailer record by ID, including trailer number, type, ownership, license plate, current location, and current load or trip assignment. - [List trailer documents](https://docs.alvys.com/en/api/reference/trailers/list-trailer-documents.md): List all documents attached to a trailer by trailer ID, including registration, inspection reports, lease agreements, and maintenance certifications. - [Search trailer events](https://docs.alvys.com/en/api/reference/trailers/search-trailer-events.md): Search trailer telematics events with paginated POST filters — trailer, event type, date range, and load or trip context for location and status pings. - [Search trailers](https://docs.alvys.com/en/api/reference/trailers/search-trailers.md): Search trailers with paginated POST filters — trailer number, type, ownership, current status, license, home terminal, and current load or trip. - [Upload trailer document](https://docs.alvys.com/en/api/reference/trailers/upload-trailer-document.md): Upload multipart/form-data. One file per request. Max file size 10 MB. Allowed document types: Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents. Allowed MIME types: application/pdf, image/jpeg, image/png. ### Trips - [Get trip](https://docs.alvys.com/en/api/reference/trips/get-trip.md): Retrieve trip records from Alvys by trip ID, including the assigned driver and truck, sequenced stops, current status, and associated load numbers. - [List trip documents](https://docs.alvys.com/en/api/reference/trips/list-trip-documents.md): List all documents attached to a trip by trip ID, including driver-submitted PODs, scale tickets, fuel receipts, and other on-the-road paperwork. - [List trip stops](https://docs.alvys.com/en/api/reference/trips/list-trip-stops.md): List all stops on a trip by trip ID in sequence order, returning location, appointment window, arrival and departure timestamps, and stop status for each. - [Get trip stop](https://docs.alvys.com/en/api/reference/trips/get-trip-stop.md): Retrieve a single trip stop by trip and stop ID, including the location, appointment window, arrival and departure timestamps, and stop-level notes. - [Search trips](https://docs.alvys.com/en/api/reference/trips/search-trips.md): Search trips with paginated POST filters — driver, truck, status, load number, planned pickup and delivery windows, origin, and destination. - [Assign trip](https://docs.alvys.com/en/api/reference/trips/assign-trip.md): Assign a driver, truck, and trailer to a trip in Alvys by trip ID, setting the resources that will move the load through pickup and delivery stops. - [Dispatch trip](https://docs.alvys.com/en/api/reference/trips/dispatch-trip.md): Dispatch an assigned trip in Alvys by trip ID, transitioning the trip from Assigned to Dispatched and notifying the driver on the mobile companion app. - [List trip check calls](https://docs.alvys.com/en/api/reference/trips/list-trip-check-calls.md): Returns the check calls (driver status updates) logged on a trip, most recent first. - [Log a trip check call](https://docs.alvys.com/en/api/reference/trips/log-a-trip-check-call.md): Logs a check call (driver status update) on an in-progress trip. Only accepted while the trip is Covered, Dispatched, or In Transit. - [Upload trip document](https://docs.alvys.com/en/api/reference/trips/upload-trip-document.md): Upload multipart/form-data. One file per request. Max file size 25 MB. Allowed document types: Proof of Delivery, Bill of Lading, Carrier Rate Confirmation, Load Manifest, Trip Report, Temp. Log, Proof of Pickup, Scale Ticket, Notice of Assignment, NOA, Shipping Labels. Allowed MIME types: applicati… - [Change trip document type](https://docs.alvys.com/en/api/reference/trips/change-trip-document-type.md): Change the document type of a file already attached to a trip, for example filing a driver upload that arrived as Unclassified. - [Set stop appointment](https://docs.alvys.com/en/api/reference/trips/set-stop-appointment.md): Set or update the appointment window on a trip stop by trip and stop ID, including scheduled date, start and end time, and appointment type. - [Record stop arrival](https://docs.alvys.com/en/api/reference/trips/record-stop-arrival.md): Record the arrival timestamp on a trip stop by trip and stop ID, marking when the driver checked in at the shipper or consignee location. - [Record stop departure](https://docs.alvys.com/en/api/reference/trips/record-stop-departure.md): Record the departure timestamp on a trip stop by trip and stop ID, marking when the driver left the shipper or consignee location for the next stop. - [Clear stop arrival](https://docs.alvys.com/en/api/reference/trips/clear-stop-arrival.md): Clear a recorded arrival timestamp on a trip stop by trip and stop ID, resetting the arrival event so drivers or dispatchers can log the correct time. - [Create stop reference](https://docs.alvys.com/en/api/reference/trips/create-stop-reference.md): Create a custom reference on an existing trip stop, optionally tied to a catalog definition, with values up to 40 characters. - [Update stop reference](https://docs.alvys.com/en/api/reference/trips/update-stop-reference.md): Update an existing custom reference on a trip stop, requiring If-Match with the current trip ETag from trip or stop reads. - [Create trip reference](https://docs.alvys.com/en/api/reference/trips/create-trip-reference.md): Create a custom reference on an existing trip, optionally tied to a catalog definition, with values up to 40 characters. - [Update trip reference](https://docs.alvys.com/en/api/reference/trips/update-trip-reference.md): Update an existing custom reference on a trip, requiring If-Match with the current trip ETag from Get trip or a prior write. ### Trucks - [List trucks](https://docs.alvys.com/en/api/reference/trucks/list-trucks.md): List trucks in your Alvys fleet with pagination, returning truck number, make and model, VIN, ownership, current driver, and last reported location. - [Get truck](https://docs.alvys.com/en/api/reference/trucks/get-truck.md): Retrieve a single truck record by ID, including truck number, make and model, VIN, license plate, current driver, and last reported GPS position. - [List truck documents](https://docs.alvys.com/en/api/reference/trucks/list-truck-documents.md): List all documents attached to a truck by truck ID, including registration, IFTA credentials, inspection reports, and lease or title paperwork. - [Search truck events](https://docs.alvys.com/en/api/reference/trucks/search-truck-events.md): Search truck telematics events with paginated POST filters — truck, event type, date range, and load or trip context for location, HOS, and status pings. - [Search trucks](https://docs.alvys.com/en/api/reference/trucks/search-trucks.md): Search trucks with paginated POST filters — truck number, make and model, ownership, home terminal, current driver, and active or inactive status. - [Upload truck document](https://docs.alvys.com/en/api/reference/trucks/upload-truck-document.md): Upload multipart/form-data. One file per request. Max file size 10 MB. Allowed document types: Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents. Allowed MIME types: application/pdf, image/jpeg, image/png. ### Users - [List users](https://docs.alvys.com/en/api/reference/users/list-users.md): List user accounts in your Alvys tenant, including full name, email, role assignments, subsidiary access, and enabled or disabled account status. - [Search users](https://docs.alvys.com/en/api/reference/users/search-users.md): Search Alvys user accounts with paginated POST filters — name, email, role, subsidiary access, and enabled or disabled account status. ### Subsidiaries - [List subsidiaries](https://docs.alvys.com/en/api/reference/subsidiaries/list-subsidiaries.md): List the subsidiaries of your own company so an integration can resolve a subsidiary id to a recognizable name, MC or DOT number, and remit address. - [Get subsidiary](https://docs.alvys.com/en/api/reference/subsidiaries/get-subsidiary.md): Retrieve a single subsidiary of your own company by id, returning its name, type, MC and DOT numbers, default equipment type, and remit address. ### Visibility - [Get inbound visibility history](https://docs.alvys.com/en/api/reference/visibility/get-inbound-visibility-history.md): Retrieve the inbound visibility update history for a load by load number, listing every position ping, ETA, and status event received from carriers. - [Get outbound visibility history](https://docs.alvys.com/en/api/reference/visibility/get-outbound-visibility-history.md): Retrieve the outbound visibility update history for a load by load number, listing every position ping and status event Alvys pushed to customer platforms. - [Search outbound visibility errors](https://docs.alvys.com/en/api/reference/visibility/search-outbound-visibility-errors.md): Search outbound visibility delivery errors with paginated POST filters — customer platform, load number, error type, and failure date range for troubleshooting. - [Record asset location](https://docs.alvys.com/en/api/reference/visibility/record-asset-location.md): Record a driver, truck, or trailer position from an external ELD or telematics source, so third-party feeds drive Alvys load and asset tracking. - [Record asset telemetry](https://docs.alvys.com/en/api/reference/visibility/record-asset-telemetry.md): Record a driver, truck, or trailer position together with the speed, heading, odometer, fuel level, and ambient temperature read at the same moment. ## OpenAPI Specs - [alvys](/openapi/alvys.json)