Changelog

​

Protocol revision support

​

Added

• Tool safety hints. Every tool now advertises MCP annotations — readOnlyHint, destructiveHint, idempotentHint, and openWorldHint — derived from the same Read/Write/Destructive classification the server enforces, so the advertised hint always matches the enforced policy. Clients use these to decide when to ask a human before running a tool. The beta surface is read-only, so every currently visible tool is marked readOnlyHint: true and destructiveHint: false; the hints matter once write tools are enabled, and are in place ahead of that.
• Server usage guidance. The server publishes natural-language instructions describing how to use the surface — that tool visibility is fixed per deployment, that unknown parameters are rejected rather than ignored, and that searches are 0-based and paginated. Clients that surface server instructions will pass this to the model automatically.

​

Changed

• Stable tool ordering. tools/list and prompts/list return entries sorted by name, so the catalog no longer varies between requests. This makes client-side caching reliable and improves prompt-cache hit rates when the tool list is included in model context.
• GET and DELETE on /mcp return 405 Method Not Allowed. These were the legacy session verbs — GET opened a server-to-client stream and DELETE ended a session. Revision 2026-07-28 is sessionless, so neither is offered. They now answer 405 (a capability signal) rather than 400 or 401, so a client probing for session support gets an unambiguous answer without a token.
• offline_access is no longer advertised in scopes_supported. A refresh token is not a requirement of this resource, so the protected-resource metadata no longer lists it. Clients that want a refresh token still request it from the authorization server as before. This shortens the consent screen.

​

Fixed

• Argument errors are actionable instead of generic. A missing required argument, or one of the wrong type (for example page: "not-an-int"), previously returned An error occurred. — indistinguishable from a server fault. These now return a structured [invalid_params] error naming the parameter, so an agent can correct the call and retry. This covers both tools and prompts.
• Prompt argument errors. prompts/get with a missing required argument returned the same generic error. It now returns invalid_params naming the argument.
• Malformed requests return a proper error body. A malformed JSON-RPC request now returns 400 with a JSON-RPC error rather than an empty 500.

​

What Changed?

​

What Should I Do?

​

MCP tools

• Added trips_record_arrival (Write · stop:update) — record an arrival event on a trip stop. Wraps PUT /api/p/v1/trips/{tripId}/stops/{stopId}/arrival.
• Added trips_record_departure (Write · stop:update) — record a departure event on a trip stop. The server enforces that an arrival must exist first. Wraps PUT /api/p/v1/trips/{tripId}/stops/{stopId}/departure.
• Added trips_update_stop_appointment (Write · stop:update) — update the appointment (or FCFS window) on a trip stop. scheduleType must be APPT or FCFS; appointmentDate is required when scheduleType=APPT, and windowBegin is required when scheduleType=FCFS. Wraps PUT /api/p/v1/trips/{tripId}/stops/{stopId}/appointment.
• Removed trips_update_stop_status — the single combined tool is replaced by the three purpose-built tools above. Callers should migrate to the specific tool for the action they want to take.
• Added trucks_events_search (Read · truck:read) — fetch truck events (maintenance, schedule, availability) for one or more trucks over a date range, mirroring drivers_events_search. Pass truckIds (Alvys truck ids, not unit numbers) and a startDate; endDate is optional. Returns a flat event list, not paged — an empty list means no events in the range.

​

Fixed

• Browser-based MCP clients can complete discovery. The protected-resource metadata endpoints and /mcp now answer cross-origin requests and OPTIONS preflights, so a client that runs guided OAuth in a browser (for example MCP Inspector) can finish the handshake instead of failing on preflight.
• Consistent authorization for settlement-statement-only tokens. A user token carrying only settlement-statement permissions no longer passes the carriers_* and drivers_* read tools at the MCP edge only to be rejected by the Public API downstream. Those tools now require the same carrier and driver read permissions their underlying endpoints enforce, so both sides agree on the outcome.

​

What changed

• 0-based paging on every search tool. page defaults to 0 and responses echo the request page back so agents can drive their own pager. pageSize still defaults to 25 (max 100).
• Strict argument validation. Unknown keys — at the top level or nested inside a date-range object or array element — return [invalid_params] naming the offending keys and the tool’s full valid-parameter list.
• Array filters, matching the Public API. Filters that map to /search array fields are now declared as arrays on the tool so you can pass one or many values in a single call.
• Structured date-range objects. Date-range filters are now single { start, end } objects using the same parameter names the Public API uses. An end without a start is rejected up front. invoices_search still requires at least one non-date filter alongside a range (matching the Public API); trips_search accepts a range as its only filter.

​

Tools affected

​

Migration

1. Rename any renamed parameters. In particular: unitNumber → truckNumber / trailerNumber (on trucks_search / trailers_search), truckId → truckNumber (on fuel_transactions_search), and singular mcNumber / dotNumber / loadNumber / orderNumber / tripNumber / driverId → their plural array forms on the search tools listed above.
2. Wrap single-value filters in an array. status: "Active" → status: ["Active"], mcNumber: "12345" → mcNumbers: ["12345"], and so on.
3. Collapse date pairs into { start, end } objects using the new parameter names (createdDateRange, pickupDateRange, deliveryDateRange, invoicedDateRange, paidDateRange, transactionRange).
4. Shift page down by one. page=1 (old first page) → page=0. If your code computes page from a UI index, subtract 1 at the call site.
5. Drop any unrecognized keys. If a call now returns [invalid_params], the error message lists both the rejected keys and the valid parameter set — align on that list.

​

What changed

​

How token scope works

https://alvys.com/claims/app/subsidiaries

​

What a scoped token can see and do

​

Scoped entities

​

Response code changes

​

Backward compatibility

​

Creating a scoped credential

1. Navigate to Settings → API Keys
2. Click New credential
3. Select permissions and choose the subsidiaries the credential may access — up to 3 specific subsidiaries, or All subsidiaries for tenant-wide access
4. Click Generate and store the Client ID and Secret securely

​

Public API + MCP: user-token access to read endpoints

• Fixed interactive (user-PKCE) tokens failing load:read, stop:read, trip:read, visibility:read, and carrier:read on the Public API and MCP for otherwise-privileged users. These endpoints were checking for internal permissions (ViewLoads, base Carrier) that no real user record carries. Any authenticated tenant user now passes the user-token half of those read checks, matching the in-app role gating. Machine-to-machine tokens are unchanged — they still require the corresponding OAuth scope. Every write endpoint keeps its real permission check.

​

POST /api/p/v{version}/driver-settlement-statements/search and GET /api/p/v{version}/driver-settlement-statements/{number}

• Added TransactionType on the response LineItems[]. Populated only when Category is Escrow; null for every other line item.
  • "Deposit" — money moved into the driver’s escrow account. Appears as a negative Amount.
  • "Withdrawal" — money moved out of the escrow account. Appears as a positive Amount.
• Additive and non-breaking. Existing consumers see one new nullable field. Totals and every other field are unchanged. This is the only Public API surface that returns escrow line items today; POST /api/p/v{version}/deductions/search does not.

​

POST /api/p/v{version}/invoices/carrier-payments

• Removed MarkAsPaid from the request body. The field only existed to force a Paid trip status, which Alvys does not use. Existing callers that still send markAsPaid are unaffected — the field is ignored.
• Fixed trip status in the response: when recorded payments fully cover the carrier payable, the trip now transitions to Completed instead of Paid. Partial payments leave the trip status unchanged.
• The response Status field reflects the trip’s current status after the payment is applied.

​

MCP: invoices_record_carrier_payment

• Removed the markAsPaid parameter (same behavior as the Public API change above).

• data.diff.changes — an array of domain-named change kinds (e.g. StatusChanged, RateChanged, StopReordered, AppointmentChanged). Delivered to every subscriber whenever something meaningful changed. Sub-entity changes carry a target — { "type": "Stop" | "Field", "id": "<stableId>" }.
• data.diff.previousAttributes — the previous value of every changed field visible on the public response, keyed 1:1 with the snapshot. Keyed collections (stops, references, charge lines) diff by stable id. Opt-in per subscription.

{
  "type": "load.changed",
  "data": {
    "load": { "...": "full current snapshot" },
    "diff": {
      "changes": [
        { "kind": "StatusChanged" },
        { "kind": "AppointmentChanged", "target": { "type": "Stop", "id": "abc123" } }
      ],
      "previousAttributes": { "...": "previous values (opt-in)" }
    }
  }
}

• Dashboard: turn on Include previous values on the webhook.
• API: set IncludePreviousAttributes: true when creating or updating the subscription (defaults to false).

​

What’s New?

​

What Changed?

GET  /api/p/v{version}/trips/{tripId}/check-calls
POST /api/p/v{version}/trips/{tripId}/check-calls

• List trip check calls — returns every check call recorded on the trip.
• Log a trip check call — records a new check call with a required description plus optional activity, driverId, structured location (coordinates included), and reefer setpointTemperature / returnTemperature.

​

Response Body Includes

• Core: Id, LoadNumber, TripId, TripNumber, Description
• Status: Activity, ResponseType, DriverName
• Location: structured address with coordinates
• Reefer: SetpointTemperature, ReturnTemperature
• Audit: CreatedAt, CreatedBy

​

Why?

​

What’s New

• Search finalized driver and owner-operator settlement statements with paging, line items, and totals.
• Search finalized carrier settlement statements with paging, per-trip breakdowns, line items, payments, and totals.
• Fetch a single driver, owner-operator, or carrier settlement statement by statement number.
• Filter statement searches by statement-date range, driver type, carrier, and subsidiary.

​

What Changes

• This release is additive and backward compatible.
• Only finalized statements from the Statements tab are returned. Open and Draft statements are excluded.
• Driver settlement statements may include Failed statements; these are identified through the Status field.
• Carrier settlement statements exclude Failed and Deleted statements.
• StatementDateRange is required for search requests. Both Start and End must be provided and are interpreted as inclusive UTC calendar days.
• The driver DriverType filter accepts COMPANY, OWNER_OPERATOR, or CONTRACTOR, case-insensitive, matching the /drivers endpoint.
• Monetary values are returned as { Amount, Currency } objects.
• Access uses existing scopes:
  • driver:read for driver settlement statements
  • carrier:read for carrier settlement statements

​

Endpoints Affected

• POST /p/v1.0/driver-settlement-statements/search (new) — search finalized driver and owner-operator settlement statements.
• GET /p/v1.0/driver-settlement-statements/{number} (new) — fetch a single driver or owner-operator settlement statement by statement number.
• POST /p/v1.0/carrier-settlement-statements/search (new) — search finalized carrier settlement statements.
• GET /p/v1.0/carrier-settlement-statements/{number} (new) — fetch a single carrier settlement statement by statement number.

​

What’s New

• Assign a carrier to a trip — assign a carrier, and optionally a driver, truck, and trailer, to a trip.
• Dispatch a trip — dispatch a covered trip so dispatch can be triggered from your own workflow.
• Filter trips by driver, truck, or trailer — narrow trip search to a specific driver or piece of equipment.
• Update a carrier’s status — set a carrier’s status (e.g. Active, Do Not Load) to keep records in sync with your compliance and vetting systems.
• Carrier contacts in the carrier response — read carrier contact details without extra calls.

​

What Changes

• All changes are additive and backward compatible.
• The new trip filters (driverId, truckId, trailerId) are optional. Each is valid on its own or alongside existing search parameters; driverId matches primary, secondary, and owner-operator assignments.
• Carrier responses now include a Contacts collection (name, email, phone, mobile, title, and a primary-contact flag) on both the get-by-id and search responses.
• Assigning a carrier requires carrierId and dispatcherId; driver2Id cannot be sent without driver1Id. Assets are referenced by id — resolve them via their search endpoints first.
• Dispatch requires the trip to be Covered (carrier and assets assigned); otherwise the request is rejected.
• Updating carrier status supports optimistic concurrency via the If-Match header and returns a fresh ETag for the next update.

​

Endpoints Affected

• POST /p/v1.0/trips/{tripId}/assign (new) — assign a carrier and optional assets; returns the updated trip.
• POST /p/v1.0/trips/{tripId}/dispatch (new) — dispatch a covered trip; returns the updated trip.
• POST /p/v1.0/trips/search (updated) — now accepts driverId, truckId, and trailerId filters.
• PATCH /p/v1.0/carriers/{carrierId}/status (new) — update a carrier’s status; returns 204 No Content with a fresh ETag.
• GET /p/v1.0/carriers/{id} and POST /p/v1.0/carriers/search (updated) — responses now include Contacts.

​

What’s New?

​

What Changed?

POST /api/p/v{version}/tenders/search
GET  /api/p/v{version}/tenders/{tenderId}
POST /api/p/v{version}/tenders
POST /api/p/v{version}/tenders/update
POST /api/p/v{version}/tenders/cancel
POST /api/p/v{version}/tenders/{tenderId}/accept
POST /api/p/v{version}/tenders/{tenderId}/accept-updates
POST /api/p/v{version}/tenders/{tenderId}/accept-cancel
POST /api/p/v{version}/tenders/{tenderId}/reject

• Search & get — query tenders and retrieve full tender detail.
• Create / update / cancel — ingest load tenders (including EDI 204-originated tenders) programmatically.
• Accept / reject — respond to a tender; accepting creates the corresponding load in Alvys.
• Accept updates / accept cancellation — apply an inbound tender update or cancellation to the linked load.

​

Why?

​

What’s New?

​

What Changed?

curl --location --request PATCH 'https://integrations.alvys.com/api/p/v1.0/loads/3039979' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'If-Match: "8DBAC1F2E3..."' \
--data-raw '{
  "orderNumber": "2026-00471"
}'

​

Preventing Accidental Overwrites

​

Validation & History

• A blank or empty Order Number is rejected with 400 Bad Request — the same rule as the internal Order Number update.
• Every change is written to the load’s history (the same audit trail as the UI path).
• EDI-originated loads are rejected. The Order Number on an EDI load is locked to the value received on the inbound tender and cannot be changed through this endpoint.

​

Endpoints Affected

​

Response Codes

​

What’s New?

​

What Changed?

• Read tools across core entities — loads, trips, carriers, customers, drivers, trucks, trailers, invoices, deductions, fuel transactions, tenders, visibility history, and documents.
• Write tools (opt-in) — create/accept/reject tenders, record carrier and customer payments, record financing, assign and dispatch trips, update carrier status, upload documents, record stop arrivals/departures, and update stop appointments.
• Curated prompts (v1) — guided multi-step workflows such as find_and_cover_load, dispatch_driver, carrier_onboarding, settlement_reconciliation, and track_shipment.

​

Authentication

• Machine-to-machine — Auth0 client-credentials tokens, same as the Public API.
• User sign-in — OAuth 2.1 with PKCE per the MCP specification, including protected-resource discovery (RFC 9728) and resource indicators (RFC 8707), so interactive clients like Claude can sign in as a user.

​

Governance & Safety

• Tenant isolation is enforced from the token — never from the request body.
• Every tool is classified Read / Write / Destructive with runtime gates; write tools are disabled unless explicitly enabled.
• Each tool requires a matching granular API permission (e.g. tender:read, invoice:update).
• All calls are rate-limited, size-capped, and audit-logged.

​

Why?

​

What’s new

​

Why it matters

• Real-time CRM sync — push customer records straight into Alvys from your TMS, ERP, or CRM instead of entering them by hand.
• Conflict-safe edits — ETag / If-Match optimistic concurrency means two concurrent edits never silently overwrite each other.

​

Create

POST /api/p/v1.0/customers
Authorization: Bearer <token with customer:create>
Content-Type: application/json

{
  "Name": "Acme Logistics",
  "Type": "Customer",
  "CompanyNumber": "ACME-1",
  "Status": "Active",
  "BillingAddress": { "Street": "1 Main", "City": "City", "State": "NY", "Zip": "10001" },
  "Email": ["billing@acme.example"],
  "Phone": ["555-1234"]
}

​

Update (partial)

PATCH /api/p/v1.0/customers/{id}
Authorization: Bearer <token with customer:update>
If-Match: "etag-from-prior-read"

{ "Status": "Inactive" }

​

Delete

DELETE /api/p/v1.0/customers/{id}
Authorization: Bearer <token with customer:delete>
If-Match: "etag-from-prior-read"

​

Supported writable fields

​

Field validation

​

Request behavior

​

Write and read responses

​

Access

• customer:read — GET / search
• customer:create — POST
• customer:update — PATCH
• customer:delete — DELETE

​

FAQ

​

What’s New?

​

What Changed?

• load.changed
• trip.changed

​

Event Envelope

{
  "id": "93d579d3-6b50-4f97-8764-1ad07c3efd97-d900dc51-...-0",
  "type": "load.changed",
  "timestamp": "2026-05-22T09:19:52.652Z",
  "version": "v1",
  "data": { /* event-specific payload - see below */ }
  // Other envelope fields are omitted from this example for brevity.
}

​

load.changed

{
  "load": {
    "id": "93d579d3-6b50-4f97-8764-1ad07c3efd97",
    "loadNumber": "3039979",
    "orderNumber": "ABC-12-007",
    "status": "Open",
    "loadType": "Revenue",
    "customerRate": {
      "amount": 1749.06,
      "currency": 840
    }
    // Full Public-API load object - same fields as GET /p/v1.0/loads/{loadNumber}.
    // Other fields (stops, charges, references, etc.) omitted here for brevity.
  }
}

​

trip.changed

{
  "trip": {
    "id": "dd5ba174abe845568f5e5c2a850db8ca",
    "tripNumber": "3039979",
    "status": "Open",
    "loadNumber": "3039979",
    "orderNumber": "ABC-12-007",
    "tripValue": {
      "amount": 1599.06,
      "currency": 840
    }
    // Full Public-API trip object - same fields as GET /p/v1.0/trips/{tripId}.
    // Other fields (driver, truck, stops, accessorials, etc.) omitted here for brevity.
  }
}

​

Endpoints Affected

• GET /p/v1.0/webhooks/event-types now returns load.changed and trip.changed.
• POST /p/v1.0/webhooks / PUT /p/v1.0/webhooks/{id} accept the new event type values in the eventTypes array.

​

Why?

• React to load and trip operational changes in real time, without polling.
• Reduce overall API call volume on /loads and /trips.
• Drive downstream automations (factoring, tracking, billing) the moment an operational state changes.
• Keep audit trails consistent through the existing webhook Delivery Logs UI.

​

What’s New?

​

What Changed?

​

Subscribing

​

Envelope (general structure)

​

*.document.uploaded payload (general structure)

{
  "id": "00000000-0000-0000-0000-000000000000-00000000-0000-0000-0000-000000000000",
  "type": "trip.document.uploaded",
  "timestamp": "2026-05-13T09:16:30.9797738+00:00",
  "version": "v1",
  "etag": "00000000-0000-0000-0000-000000000000",
  "data": {
    "tripId": "00000000000000000000000000000000",
    "document": {
      "id": "00000000-0000-0000-0000-000000000000",
      "attachmentPath": "bol.pdf",
      "attachmentType": "Bill of Lading",
      "attachmentSize": 10000,
      "uploadedAt": "2026-05-13T09:16:30.9797738+00:00",
      "parentId": "1000000",
      "parentType": "Trip",
      "uploadedBy": "00000000000000000000000000000000",
      "downloadUrl": "{url}",
      "expiresAt": "2026-05-13T09:26:35.3227049+00:00"
    }
  }
}

• data.tripId is the trip GUID (the natural public identifier returned by GET /p/v1.0/trips/{tripId}).
• data.document.parentId on a trip document is the load number ("1000000") — matching how trip documents are stored internally and returned by GET /loads/{loadNumber}/documents.
• attachmentType is a human-readable Alvys document type (e.g. "Bill of Lading", "Proof of Delivery", "Rate Confirmation") — same value returned by the document Public API endpoints.
• uploadedBy is the user id (GUID) of the uploader.

​

*.document.deleted payload (general structure)

// load.document.deleted
{
  "id": "00000000-0000-0000-0000-000000000000-00000000-0000-0000-0000-000000000000",
  "type": "load.document.deleted",
  "timestamp": "2026-05-13T16:05:22.118+00:00",
  "version": "v1",
  "etag": "00000000-0000-0000-0000-000000000000",
  "data": {
    "loadNumber": "1000000",
    "document": {
      "id": "00000000-0000-0000-0000-000000000000",
      "attachmentPath": "bol.pdf",
      "attachmentType": "Bill of Lading",
      "attachmentSize": 10000,
      "uploadedAt": "2026-05-13T09:16:30.9797738+00:00",
      "uploadedBy": "00000000000000000000000000000000",
      "parentId": "1000000",
      "parentType": "Load"
    }
  }
}

​

Behavior notes

• An event fires only when a document is created or soft-deleted — rename, retype, and other metadata-only edits do not generate deliveries.
• Pre-signed downloadUrl is short-lived (≤ 15 minutes). Pull the file promptly, or fall back to GET /p/v1.0/{parent}/{parentId}/documents/{documentId} if it expires.

​

Endpoints Affected

​

Webhook subscription management

• GET /p/v1.0/webhooks/event-types — returns the full catalog including the new document event types.
• POST /p/v1.0/webhooks — create a subscription that selects any combination of the new events.
• PUT /p/v1.0/webhooks/{id} — update an existing subscription to add or remove document events.
• GET /p/v1.0/webhooks/{id} — inspect which events a subscription is selecting.
• GET /p/v1.0/webhooks/{id}/deliveries — delivery history for the new events flows through the same logs surface as tender.* and *.status.changed.

​

Document endpoints driving the events

​

Fallback retrieval (if a downloadUrl expires)

GET /p/v1.0/{parent}/{parentId}/documents/{documentId}

​

Why?

• ⚡ Real-time document automation — POD-driven invoice automation, factoring, document management, and EDI 210 invoice validation no longer wait on a poll loop.
• 🔁 Lower API load — eliminates polling traffic against six different parent endpoints.
• 🎯 Subscribe narrowly — events are scoped per entity (load.* vs driver.* vs carrier.* …). A factoring integration that only cares about load-side documents won’t receive driver med-card updates.
• 🧾 Built-in audit trail — every delivery attempt is recorded and visible in the Webhook details page.
• 🔗 Direct download — every *.uploaded event carries a pre-signed download URL.

​

Who has access?

​

Frequently Asked Questions (FAQ)

​

What’s New?

​

What Changed?

load.status.changed
trip.status.changed

GET /p/v1.0/webhooks/event-types

​

Event Envelope

{
  "id": "…",
  "type": "load.status.changed",
  "timestamp": "2026-05-04T14:32:11.482Z",
  "version": "1",
  "data": { /* event-specific payload — see below */ }
  // Other envelope fields are omitted from this example for brevity.
}

​

load.status.changed

{
  "previousStatus": "Covered",
  "status": "Dispatched",
  "load": {
    "id": "…",
    "loadNumber": "1006321",
    "status": "Dispatched"
    // Full Public-API load object — same fields as GET /p/v1.0/loads/{loadNumber}.
    // Other fields (customer, stops, charges, references, etc.) omitted here for brevity.
  }
}

​

trip.status.changed

{
  "previousStatus": "Dispatched",
  "status": "InTransit",
  "trip": {
    "id": "…",
    "tripNumber": "T-1006321-1",
    "status": "InTransit"
    // Full Public-API trip object — same fields as GET /p/v1.0/trips/{tripId}.
    // Other fields (driver, truck, stops, accessorials, etc.) omitted here for brevity.
  }
}

​

Behavior

• Events are emitted only on actual transitions — when status differs from previousStatus. No-op writes do not generate deliveries.
• load / trip may be null if the snapshot read fails or if the payload exceeded the size limit and was stripped. The previousStatus and status fields are always present so consumers can still react to the transition and refetch via GET /loads/{id} or GET /trips/{id} if needed.
• Deliveries are signed (X-Alvys-Signature), retried with exponential backoff, and auto-disable subscriptions after sustained failures — identical to existing tender.* events.

​

Endpoints Affected

• GET /p/v1.0/webhooks/event-types — now returns load.status.changed and trip.status.changed
• POST /p/v1.0/webhooks / PUT /p/v1.0/webhooks/{id} — accept the new event type values in the eventTypes array

​

Why?

• React to load and trip status changes in real time, without polling
• Reduce overall API call volume on /loads and /trips
• Drive downstream automations (factoring, tracking, billing) the moment an operational state changes
• Keep audit trails consistent through the existing webhook Delivery Logs UI

​

What’s New?

​

What Changed?

POST /p/v1.0/invoices/carrier-payments
POST /p/v1.0/invoices/customer-payments
POST /p/v1.0/invoices/financing

​

Carrier Payments

{
  "tripId": "string",
  "amount": {
    "value": 1000.00,
    "currency": "USD"
  }
}

​

Customer Payments

{
  "loadId": "string",
  "amount": {
    "value": 2500.00,
    "currency": "USD"
  }
}

• paidAt
• totalPaid
• payments[]

​

Financing

{
  "loadId": "string",
  "reserveAmount": {
    "value": 500.00,
    "currency": "USD"
  },
  "escrowAmount": {
    "value": 200.00,
    "currency": "USD"
  }
}

​

Endpoints Affected:

• POST /p/v1.0/invoices/carrier-payments
• POST /p/v1.0/invoices/customer-payments
• POST /p/v1.0/invoices/financing

​

Why?

• Faster integration with payment and finance platforms
• Better automation for receivables and payables
• Support for factoring and escrow workflows
• Reduced manual entry of financial transactions
• Improved accounting visibility across loads and trips

​

What’s New?

​

What Changed?

• when includeDeleted is omitted, Trip Search returns only visible, non-deleted trips
• when includeDeleted=false, Trip Search also returns only visible, non-deleted trips

• superseded base trips
• hidden child legs from chained splits
• hidden child legs from split-cancel / unsplit / restore scenarios

​

What isDeleted Means

• isDeleted=true means the trip is deleted or no longer visible and should be treated as inactive for sync
• isDeleted=false means the trip is a current visible leg

​

Common Scenarios

​

Example

​

Endpoint Affected

POST /p/v1.0/trips/search

​

Why?

• reliable tombstone detection for invisible and superseded trips
• better support for updatedSince and updatedAtRange polling
• more consistent synchronization for split, re-split, cancel-split, and restore scenarios

​

What’s New?

​

What Changed?

GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export

​

Delivery Attempt Header

​

statusReason Added to Webhook Payloads

{
  "statusReason": "Normal Status"
}

​

Delivery Logs Export

​

Query Parameters

​

Export Behavior

1. Format=csv or Format=json in the query string takes precedence when provided.
2. Otherwise, the Accept header is used.
3. Otherwise, the response defaults to JSON.

​

Breaking Change: Delivery Log Filters Now Accept Arrays

​

Before

{
  "status": "failed",
  "eventType": "load.updated"
}

​

After

{
  "status": ["failed"],
  "eventType": ["load.updated"]
}

​

Endpoints Affected

• GET /p/v{version}/webhooks/{webhookId}/delivery-logs
• GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export

​

Why?

• better retry visibility for webhook consumers
• clearer status context in outbound payloads
• easier export and audit of webhook delivery history
• more flexible filtering for delivery log queries and exports

​

What’s New?

​

What Changed?

​

Loads

{
  "tenderId": "string | null",
  "requiredEquipment": [
    "Reefer"
  ]
}

• orphaned loads are now treated as non-existent
• load search totals exclude abandoned loads with no trips
• load document and note operations now return 404 for orphaned loads

​

Trips

{
  "orderNumber": "string | null"
}

• split or invisible trips can now be returned as isDeleted: true when includeDeleted=true
• GET /p/v{version}/trips now supports includeDeleted
• POST /p/v{version}/trips/search now allows updatedAtRange as the only filter
• load references of type service_exception are now exposed
• carrier payloads are aligned between single-trip retrieval and trip search

​

Carriers

​

Tenders

​

Additional response schema updates

• CarrierResponse now includes:
  • PaymentMethod
  • ExternalIds
  • FactoringCompany
• DriverResponse, TruckResponse, and TrailerResponse now include:
  • LicenseCountry
• FuelResponse now includes:
  • Description
• FuelResponsePumpLocation now includes:
  • State

​

Trip rate schema updates

• DriverRatePolicyResponse now includes:
  • CustomerLineHaulDeductionRate
  • PerMileRate
  • PerMileDeductionRate
• PerLoadRate now uses a dedicated PerLoadRateDto
• MileageRateDto now includes:
  • UseHighestTier
• PerTripRateDto now includes:
  • Tiers
  • MileageType
• PerTripRateDto.Rate is now marked as deprecated in the schema

​

Error-response documentation updates

• 401 Unauthorized
• 403 Forbidden
• 429 Too Many Requests

​

Why?

• better load and trip sync reliability for polling integrations
• clearer identification of tender-originated loads
• better visibility into order linkage at the trip level
• more complete carrier search results
• stronger consistency between related trip endpoints
• richer master-data payloads for carriers, drivers, trucks, trailers, and fuel records
• more expressive trip rate schemas

​

What’s New?

​

What Changed?

GET    /api/p/v{version}/trips/{tripId}/stops
GET    /api/p/v{version}/trips/{tripId}/stops/{stopId}
PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
DELETE /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/departure
PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/appointment

• Record stop arrival — body takes a required arrivedAt timestamp; returns the updated stop.
• Clear stop arrival — removes a previously recorded arrival.
• Record stop departure — body takes a required departedAt timestamp; returns 422 if the stop is not in a state that can be departed.
• Set stop appointment — update the stop’s scheduleType, loadingType, and appointment window.

​

Why?

​

What’s New?

​

What Changed?

GET    /api/p/v1/loads/{loadNumber}/notes
POST   /api/p/v1/loads/{loadNumber}/notes
DELETE /api/p/v1/loads/{loadNumber}/notes/{noteId}

• List load notes — returns all notes on the load.
• Create load note — body takes description, noteType, and an optional client-supplied id; returns 201 with the created note.
• Delete load note — returns 204 on success.

​

Response Body Includes

• Id, Description, NoteType
• CreatedAt, CreatedBy
• CreatedById — the unique identifier of the user who created the note (added April 2026), so integrations can attribute notes to a user by id instead of parsing display names.

​

Why?

​

What’s New?

​

What You Can Do

• Receive real-time tender lifecycle events
• Automatically trigger workflows in your system
• Improve integration speed and responsiveness

​

Included in This Release

​

Event Delivery

• Event type
• Unique event ID
• Timestamp
• Secure HMAC signature

​

Automatic Retries

• Your endpoint returns a server error (5xx)
• A timeout occurs
• A temporary network failure happens

​

Security & Verification

• HMAC-SHA256 signature verification
• Replay protection using timestamps
• HTTPS-only delivery
• Endpoint ownership verification during setup

​

Why This Matters

• EDI over API integrations
• Automated tender workflows
• Faster operational response
• Secure third-party integrations

​

Documentation

• Webhook Lifecycle & Configuration
• Event Delivery & Reliability
• Security & Signature Verification

​

What’s New?

​

What Changed?

"Temperature": {
  "SetpointTemperature": 70.0,
  "SetpointTemperatureMax": 75.0,
  "ControlMode": "Start/Stop"
},

"RequiredEquipment": [
  "Reefer"
]

​

Temperature

• SetpointTemperature – The required target temperature.
• SetpointTemperatureMax – Optional maximum temperature when a range is defined.
• ControlMode – Expected operational mode (Continuous or Start/Stop).

​

RequiredEquipment

"RequiredEquipment": ["Reefer", "Van"]
"RequiredEquipment": ["Van"]
"RequiredEquipment": ["Flatbed", "StepDeck"]

​

Endpoints Affected:

• POST /api/p/{version}/trips/search
• GET /api/p/{version}/trips/{id}

​

Why?

• Improved visibility into temperature-controlled trip requirements
• Structured equipment data for easier validation and integration
• Better support for compliance workflows and custom tracking applications

​

What’s New?

​

What Changed?

"references": [
  {
    "id": "string",
    "referenceId": "string",
    "name": "string",
    "value": "string",
    "type": "Text",
    "access": "Public",
    "origin": "string"
  }
]

​

Endpoints Affected

• GET /api/p/v{version}/trips/{id} and POST /api/p/v{version}/trips/search
• GET /api/p/v{version}/drivers/{id} and POST /api/p/v{version}/drivers/search
• GET /api/p/v{version}/trucks/{id} and POST /api/p/v{version}/trucks/search
• GET /api/p/v{version}/trailers/{id} and POST /api/p/v{version}/trailers/search

​

Why?

​

What’s New?

​

What Changed?

 "RatesV2": [
                    {
                        "PolicyId": "c00fda1001ec4a11100affdb0234de00",
                        "PolicyName": "Custom Rate",
                        "PerTripRate": {
                            "Rate": 250.0,
                            "RateId": "1",
                            "RateName": "Per Trip",
                            "LineItems": [
                                {
                                    "Description": "1 trip @ $250",
                                    "Amount": {
                                        "Amount": 250.0,
                                        "Currency": 840
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "PolicyId": "a00fba1001ec4a11100aaddff0234de00",
                        "PolicyName": "Public API",
                        "TripValuePercentageRate": {
                            "Percentage": 25.0,
                            "RateId": "2",
                            "RateName": "% of Trip Value",
                            "LineItems": [
                                {
                                    "Description": "25% of $3,800",
                                    "Amount": {
                                        "Amount": 950.0,
                                        "Currency": 840
                                    }
                                }
                            ]
                        }
                    }
                ]

​

Endpoints Affected

• GET /api/p/{version}/trips
• POST /api/p/{version}/trips/search

​

Why?

• Understand which rules and policies were applied to determine each payout.
• Align backend integrations with the new internal pay policy engine for consistent reporting and reconciliation.

​

What’s New?

​

What Changed?

• A deduction must include either DriverId or TruckId — one of them is required.
• OwnerOperatorId is optional and may be used only to override the current owner of the asset. It is never the primary deduction subject.
• If DriverId is provided → the deduction appears in that driver’s deduction list.
• If TruckId is provided → the deduction appears in that truck’s deduction list.
• For creating a deduction, the amount must be negative and less than - 1.00.
• Only "Once" frequency is supported.
• Requires a valid Bearer token with the appropriate scope (deduction:read, deduction:create, or deduction:delete).

​

Why?

​

What Changed?

​

Response Example

[
  {
    "id": "a314c7cd-783a-4807-8771-06406a9e490a",
    "AttachmentPath": "Loads-1759237626.pdf",
    "AttachmentType": "Customer Rate Confirmation",
    "AttachmentSize": 170225,
    "UploadedAt": "2025-09-30T13:07:07+00:00",
    "ParentId": "3022259",
    "ParentType": "Load",
    "UploadedBy": "7190175eecc3408e90d7173f4ece0e59",
    "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/Loads-1759237626.pdf?...",
    "ExpiresAt": "2025-09-30T15:12:15.9506343+00:00"
  }
]

​

Why?

​

What’s New?

​

What Changed?

"OfficeId": "string",

​

Endpoints Affected:

• POST /api/p/{version}/loads/search
• GET /api/p/{version}/loads/{id}

​

Why?

​

What’s New?

​

What Changed?

• New endpoints:
  • POST /api/p/v{version}/carriers/{carrierId}/document
  • POST /api/p/v{version}/drivers/{driverId}/document
  • POST /api/p/v{version}/loads/{loadNumber}/document
  • POST /api/p/v{version}/trailers/{trailerId}/document
  • POST /api/p/v{version}/trips/{tripId}/document
  • POST /api/p/v{version}/trucks/{truckId}/document
• Validation by entity:
  • Carrier→ Carrier Agreement, Carrier Application, Carrier Authority, Carrier Onboarding, Other Documents
  • Driver→ License, Drug Test, Medical (suggested rename: Medical Card), W9 Form, Operating Authority, Other Documents
  • Truck/Trailer → Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents
  • Loads→ 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
  • Trips → Proof of Delivery (POD), Bill of Lading (BOL), Carrier Rate Confirmation, Load Manifest, Trip Report, Temperature Log, Proof of Pickup, Scale Ticket, Notice of Assignment (NOA), Shipping Labels
• Error handling standardized: 400 invalid DocumentType or file too large 401 invalid/expired token 403 missing scopes 404 parent not found/deleted 415 unsupported content type 429 rate limit exceeded

​

Example — Upload Document to Load

curl -X POST "{{host}}/api/p/v1/loads/1006321/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "File=@Test_File.pdf" \
  -F "DocumentType=Bill of Lading"

{
  "id": "4b5c38bd-005e-4903-a4ee-45ca5e86411a",
  "AttachmentPath": "DOC-1757343192.jpeg",
  "AttachmentType": "Bill of Lading",
  "AttachmentSize": 5245329,
  "UploadedAt": "2025-09-08T14:53:12Z",
  "ParentId": "1006321",
  "ParentType": "Load"
}

​

Why?

​

What’s New?

• Lookup by ID or Company Number: Retrieve a single location by unique id or companyNumber.
• Flexible search: Filter by Statuses, LocationIds, or CreatedDateRange.
• Richer details: Get company name, type, address, contacts, and notes directly in the response.

​

What Changed?

• New endpoints:
  • GET /api/p/v{version}/locations → Single location lookup by id or companyNumber.
  • POST /api/p/v{version}/locations/search → Search and paginate results.
• Response body includes:
  • Core: Id, Name, CompanyNumber, Type, Status
  • Address: PhysicalAddress { Street, City, State, ZipCode }
  • Contacts: Email[], Phone[], Fax
  • Metadata: DateCreated, ExternalId
  • Notes: [ { Id, Description, NoteType, Time, User } ]
• Backward compatibility: No changes to existing load/trip stop payloads. Stops continue to expose companyId, but now customers can resolve those IDs via the Locations Controller for more context.

​

New Endpoints

• GET /api/p/v{version}/locations
• POST /api/p/v{version}/locations/search

​

Why?

​

What’s New?

• TransactionDate → Now included in all fuel transactions.
• Quantity → Each transaction includes the purchased quantity with value and unit of measure:

"Quantity": {
  "Value": 7.799,
  "UnitOfMeasure": "Gallons"
}

​

What’s New?

• Multi-entity support: Accessorials are now tracked for Customers, Carriers, Drivers, and OwnerOperators.
• EChecks integration: Driver and OwnerOperator accessorials can include linked eCheck numbers and amounts.
• Updated settlement logic: TotalPayable now calculates as Linehaul + Accessorials – EChecks.

​

What Changed?

• /loads → CustomerAccessorialsDetails[] added.
• /trips → New detail arrays for:
  • Carrier.AccessorialsDetails[]
  • Driver1.AccessorialsDetails[] for Driver and OwnerOperator.
• Each accessorial includes:
  • Default: Id, Type, Total { Amount, Currency }, Rate { Amount, Currency }, RateType, Uom, Quantity
  • Optional: IsPaid, ECheckNumber, StopId
  • Audit: CreatedAt, UpdatedAt, CreatedBy, UpdatedBy
• EChecks are now returned as part of trip data when relevant.
• Cancelled loads/trips → No accessorial details returned.
• Backward compatibility → Legacy totals remain available (CustomerAccessorials, Carrier.Accessorials, Linehaul, etc.), so this is a non-breaking change.

​

Example — Accessorials

{
  "Id": "acc-78901",
  "Type": "Layover Pay",
  "Total": { "Amount": 150.0, "Currency": 840 },
  "Rate": { "Amount": 75.0, "Currency": 840 },
  "RateType": "Time",
  "Uom": "Hour",
  "Quantity": 2.0,
  "ECheckNumber": "12345",
  "CreatedAt": "2024-07-11T14:30:00Z"
}

​

Endpoints Affected

• GET /api/p/v{version}/loads
• POST /api/p/v{version}/loads/search
• GET /api/p/v{version}/trips
• POST /api/p/v{version}/trips/search

​

Why?

• LoadType now appears on load objects.
• Returned values: "Revenue" or "Non-Revenue"

• GET /api/p/{version}/loads
• POST /api/p/{version}/loads/search

• Previously, deleted loads and trips were never returned.
• You can now include IncludeDeleted (boolean, optional) in your request body:
  • true → returns both active and deleted records.
  • omitted or false → returns only active records.
• When IncludeDeleted: true, every returned record includes an IsDeleted flag:
  • "IsDeleted": true for deleted items
  • "IsDeleted": false for active items
• When IncludeDeleted is omitted or false, no IsDeleted flags appear (all records are active by definition).

• POST /api/p/{version}/loads/search
• POST /api/p/{version}/trips/search

​

🔐 New Authentication

• Now get access token via auth.alvys.com/oauth/token for improved security and compliance.
• Old authentication method will soon be disabled—update your credentials using the new setup instructions.

​

🔄 Automated Pagination

• All queries now handle paging automatically.
• Large datasets load completely, with no missing records or manual adjustments.
• A built-in delay mechanism helps prevent hitting API rate limits during refreshes, improving reliability for large data pulls.

​

↔️ Nested Data Expansion

• Data queries now automatically expand up to 3 levels of nested fields.
• All relevant API data is accessible without extra manual steps.

​

🗓️ Automatic Field Type Conversion

• Key fields such as dates and numbers are now automatically converted to the correct data types during import (e.g., date columns to datetime, amounts to numbers).
• Ensures correct filtering, calculations, and visualization in your reports without manual adjustments.

​

📦 Loads Data Improvements

• Loads are imported through two queries:
  • Full Import
  • Incremental Updates
• Automatic deduplication ensures only the most recent update for each load is kept.

​

🧰 Consistent Query Structure

• All endpoints (Loads, Trips, Users, etc.) now use a unified paging and expansion pattern.
• Makes the model easier to understand, troubleshoot, and extend.

​

📊 New DAX & Reporting Features

• Added several basic DAX formulas (e.g., simple sums, counts, or averages) to help users quickly analyze and familiarize themselves with their data.
• Created a sample weekly summary report table—aggregates core metrics by week, making it easy to spot trends over time.
• These examples are intended as a starting point for your own analysis—feel free to adjust or build on them as needed.

​

📘 Improved Onboarding

• Step-by-step setup instructions are included to guide you through credential updates and data loading. You can find the link to the latest file and a quick onboarding guide here.

❗️ Important Note This change may impact metrics in your current reports — such as total trips, total mileage, total carrier rate, and others — starting today. If your reporting logic includes custom filters or scripts to automatically exclude the original (dispatched) trip when a load is split, those filters may now be obsolete. Since the original trip is no longer returned, continuing to exclude it may result in underreporting. Please review and update any custom reporting logic accordingly to ensure accurate totals going forward.

​

What’s New?

​

What Changed?

• A new token endpoint must now be used to generate access tokens:
  POST https://auth.alvys.com/oauth/token
• Tokens now include permission scopes (e.g. load:read, trip:create) that define which resources and actions the client is allowed to access
• Scope-based access enforcement is enabled for tokens generated via the new endpoint — requests without the proper scope will return 403 Forbidden
• The legacy {tenant_id} token endpoint is deprecated and will be shut down on July 31, 2025
  (tokens from this endpoint do not include scopes and are treated as read-only for now)

​

How to Request a Token

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.alvys.com/public/",
  "grant_type": "client_credentials"
}

​

Endpoints Affected:

• ✅ New (required): POST https://auth.alvys.com/oauth/token
• 🛑 Later Deprecated: POST /authentication/{tenant_id}/token (to be removed on July 31, 2025)

❗️ Important: The legacy POST /authentication/{tenant_id}/token token endpoint will be permanently shut down on July 31, 2025. All integrations using this authentication flow must be updated to use the new token endpoint before this date to avoid disruption.

• Linehaul — Base transportation cost.
• Accessorials — Additional charges (e.g., fuel surcharges, detention).
• TotalPayable — Full amount payable to the carrier.

❗️ Important: The Rate field in the Carrier object will be deprecated in a future release. We recommend updating reports and integrations to use the newLinehaul, Accessorials, and TotalPayable fields. This change will not happen immediately — there will be a transition period, and we will provide advance notice before the field is removed. Please review your current usage and plan updates accordingly to ensure a smooth transition.

• ✅ true for active
• ❌ false for inactive.

​

What’s New?

​

What Changed?

GET  /api/p/v{version}/maintenance/{id}
POST /api/p/v{version}/maintenance/search

• Get maintenance record — retrieve a single record by id.
• Search maintenance records — search and paginate records.

​

Response Body Includes

• Core: Id, PO, Reference, Description, Comments
• Classification: Category
• Asset: RelatedAsset (the truck or trailer the record belongs to)
• Financial: Amount (value + currency)
• Shop: RepairShop details
• Scheduling: Reminders
• Audit: CreatedAt, CreatedBy, ModifiedAt, ModifiedBy

​

Why?

• linehaul – Base transportation cost.
• fuelSurcharge – Fuel cost adjustments.
• customerAccessorials – Extra charges like detention or lumper fees.

• Increased Limit: The maximum number of loads allowed in the search request body has been increased from 50 to 150.
  • Impact: Users can now include more load IDs in a single search request operation.
  • Error Handling: Requests exceeding 150 load IDs will return an error message.

• DispatcherId Field: The DispatcherId field is now included in the response body for all trips endpoints.
  • Purpose: Provides the unique identifier of the dispatcher assigned to the trip for improved data tracking and integration.
  • Benefits: Enhances trip management and reporting by making dispatcher data more accessible through the API.

​

Release Date: November 11, 2024

​

What’s New?

1. Visibility Public API Endpoints:
   • Introduces endpoints for tracking asset locations and receiving real-time event updates.
2. Endpoints Overview:
   • Inbound Visibility:
     • GET /api/p/v{version}/visibility/inbound/{loadNumber}/history: Retrieve location update history for a specific load number.
   • Outbound Visibility:
     • GET /api/p/v{version}/visibility/outbound/{loadNumber}/history: Retrieve event update history sent for a specific load number.
     • POST /api/p/v{version}/visibility/outbound/errors: Search for and manually resend failed updates using a time range filter.

​

Usage

​

Inbound Visibility Example

GET /api/p/v{version}/visibility/inbound/{{loadNumber}}/history

​

Outbound Visibility Examples

GET /api/p/v{version}/visibility/outbound/{{loadNumber}}/history

​

Search Failed Updates:

POST /api/p/v{version}/visibility/outbound/errors
{
  "page": 0,
  "pageSize": 10,
  "timeRange": {
    "start": "2024-11-05T16:58:54.450Z",
    "end": "2024-11-11T16:58:54.450Z"
  }
}