> ## 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.
# Set stop appointment
> 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.
Updates the scheduling information for a specific stop within a trip.
This endpoint allows updating the stop appointment details including:
* schedule type
* loading type
* appointment date
* appointment request / confirmation flags
* delivery window (for FCFS stops)
The response returns the **updated stop object**.
***
### Endpoint
```
PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/appointment
```
***
### Request Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------ |
| version | string | Yes | API version (e.g. `1.0`). |
| tripId | string | Yes | Unique identifier of the trip. |
| stopId | string | Yes | Unique identifier of the stop. |
***
### Request Body
| Field | Type | Required | Description |
| -------------------- | ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ScheduleType | string | Yes | Schedule type of the stop (`APPT` or `FCFS`). |
| LoadingType | string | Yes | Loading type (`Live`, `Drop`, `Hook`, `Drop&Hook`). |
| AppointmentDate | string (datetime) | Conditional | Appointment date and time in **ISO-8601 UTC format**. Required when `ScheduleType = APPT`. |
| AppointmentRequested | boolean | Yes | Indicates whether an appointment has been requested. |
| AppointmentConfirmed | boolean | Yes | Indicates whether the appointment has been confirmed. |
| WindowBegin | string (datetime) | Conditional | Start of the delivery window in **ISO-8601 UTC format**. Required when `ScheduleType = FCFS`. |
| WindowEnd | string (datetime) | No | End of the delivery window in **ISO-8601 UTC format**. Used when `ScheduleType = FCFS`. If provided alongside `WindowBegin`, must be after `WindowBegin`. |
**Conditional validation rules:**
* If `ScheduleType = APPT`, you must provide `AppointmentDate`.
* If `ScheduleType = FCFS`, you must provide `WindowBegin`.
* If both `WindowBegin` and `WindowEnd` are provided, `WindowBegin` must be earlier than `WindowEnd`.
***
### Example Request Body
```json theme={null}
{
"ScheduleType": "string",
"LoadingType": "string",
"AppointmentDate": "string",
"AppointmentRequested": true,
"AppointmentConfirmed": true,
"WindowBegin": "string",
"WindowEnd": "string"
}
```
***
### Example CURL request
```bash theme={null}
curl --location --request PUT 'https://integrations.alvys.com/api/p/v1/trips/{tripId}/stops/{stopId}/appointment' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"ScheduleType": "APPT",
"LoadingType": "Live",
"AppointmentDate": "2026-03-16T12:45:43.262Z",
"AppointmentRequested": true,
"AppointmentConfirmed": true
}'
```
Replace:
* `{version}` with the API version (for example `1`)
* `{tripId}` with the actual trip ID
* `{stopId}` with the stop ID
* `YOUR_ACCESS_TOKEN` with your Bearer token
***
### Response Parameters
| Parameter | Type | Description |
| ------------------------- | ----------------- | ----------------------------------------------------- |
| Id | string | Unique identifier of the stop. |
| Address.Street | string | Street address of the stop location. |
| Address.City | string | City of the stop location. |
| Address.State | string | State of the stop location. |
| Address.ZipCode | string | ZIP code of the stop location. |
| AppointmentConfirmed | boolean | Indicates whether the appointment has been confirmed. |
| AppointmentDate | string (datetime) | Appointment date and time for the stop. |
| AppointmentRequested | boolean | Indicates whether an appointment has been requested. |
| ArrivedAt | string (datetime) | Timestamp when the stop was marked as arrived (UTC). |
| DepartedAt | string (datetime) | Timestamp when the stop was marked as departed (UTC). |
| ScheduleType | string | Schedule type (`APPT` or `FCFS`). |
| LoadingType | string | Loading type (`Live`, `Drop`, `Hook`, etc.). |
| StopType | string | Type of stop (`Pickup`, `Delivery`, `Waypoint`). |
| Status | string | Operational status of the stop. |
| Coordinates.Latitude | string | Latitude of the stop location. |
| Coordinates.Longitude | string | Longitude of the stop location. |
| References\[] | array | List of references associated with the stop. |
| References\[].Id | string | Reference identifier. |
| References\[].ReferenceId | string | External reference identifier. |
| References\[].Name | string | Name of the reference field. |
| References\[].Value | string | Value of the reference. |
| References\[].Type | string | Type of reference. |
| References\[].Access | string | Access level (`Public`, `Internal`). |
| References\[].Origin | string | Origin of the reference. |
| CompanyId | string | Identifier of the company associated with the stop. |
| CompanyNumber | string | Company registration or identification number. |
| CompanyName | string | Company name associated with the stop. |
***
### Example Response
```json theme={null}
{
"AppointmentRequested": true,
"AppointmentConfirmed": true,
"AppointmentDate": "2026-03-16T12:45:43.262Z",
"ScheduleType": "string",
"LoadingType": "string",
"Id": "string",
"Address": {
"Street": "string",
"City": "string",
"State": "string",
"ZipCode": "string"
},
"Coordinates": {
"Latitude": "string",
"Longitude": "string"
},
"Status": "string",
"StopType": "string",
"ArrivedAt": "2026-03-16T12:45:43.262Z",
"DepartedAt": "2026-03-16T12:45:43.262Z",
"References": [
{
"Id": "string",
"ReferenceId": "string",
"Name": "string",
"Value": "string",
"Type": "string",
"Access": "string",
"Origin": "string"
}
],
"CompanyId": "string",
"CompanyNumber": "string",
"CompanyName": "string"
}
```
***
### Status Codes
| Status Code | Description |
| --------------- | -------------------------------------- |
| 200 OK | Stop appointment successfully updated. |
| 400 Bad Request | Invalid request body. |
| 404 Not Found | Trip or stop could not be found. |
***
### Rate Limits
All endpoints are subject to API rate limits to ensure service stability and protect against traffic spikes.
Refer to the **Rate Limits** documentation for more information.
## OpenAPI
````yaml PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/appointment
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}/trips/{tripId}/stops/{stopId}/appointment:
put:
tags:
- Trips
summary: Set stop appointment
parameters:
- name: tripId
in: path
required: true
schema:
type: string
- name: stopId
in: path
required: true
schema:
type: string
- 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.Trips.Request.UpdateAppointmentRequest
application/json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Trips.Request.UpdateAppointmentRequest
text/json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Trips.Request.UpdateAppointmentRequest
application/*+json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Trips.Request.UpdateAppointmentRequest
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Alvys.Models.Trips.StopResponse'
'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'
'422':
description: Unprocessable Content
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.Trips.Request.UpdateAppointmentRequest:
required:
- AppointmentConfirmed
- AppointmentRequested
- LoadingType
- ScheduleType
type: object
properties:
ScheduleType:
type: string
LoadingType:
type: string
AppointmentDate:
type: string
nullable: true
AppointmentRequested:
type: boolean
AppointmentConfirmed:
type: boolean
WindowBegin:
type: string
nullable: true
WindowEnd:
type: string
nullable: true
additionalProperties: false
Alvys.Models.Trips.StopResponse:
required:
- $type
type: object
oneOf:
- $ref: '#/components/schemas/Alvys.Models.Trips.AppointmentStopResponse'
- $ref: '#/components/schemas/Alvys.Models.Trips.DeliveryWindowStopResponse'
- $ref: '#/components/schemas/Alvys.Models.Trips.WaypointStopResponse'
properties:
$type:
type: string
description: Type discriminator for polymorphic serialization
additionalProperties: false
discriminator:
propertyName: $type
mapping:
appointment:
$ref: '#/components/schemas/Alvys.Models.Trips.AppointmentStopResponse'
delivery_window:
$ref: '#/components/schemas/Alvys.Models.Trips.DeliveryWindowStopResponse'
waypoint:
$ref: '#/components/schemas/Alvys.Models.Trips.WaypointStopResponse'
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.Trips.AppointmentStopResponse:
required:
- AppointmentConfirmed
- AppointmentRequested
- Id
- References
- ScheduleType
- StopType
type: object
properties:
AppointmentRequested:
type: boolean
AppointmentConfirmed:
type: boolean
AppointmentDate:
type: string
format: date-time
nullable: true
ScheduleType:
type: string
LoadingType:
type: string
nullable: true
Id:
type: string
Address:
allOf:
- $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
nullable: true
Coordinates:
allOf:
- $ref: '#/components/schemas/Alvys.Models.Coordinates'
nullable: true
Status:
type: string
nullable: true
StopType:
type: string
ArrivedAt:
type: string
format: date-time
nullable: true
DepartedAt:
type: string
format: date-time
nullable: true
References:
type: array
items:
$ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse'
CompanyId:
type: string
nullable: true
CompanyNumber:
type: string
nullable: true
CompanyName:
type: string
nullable: true
additionalProperties: false
Alvys.Models.Trips.DeliveryWindowStopResponse:
required:
- Id
- References
- ScheduleType
- StopType
type: object
properties:
StopWindow:
allOf:
- $ref: '#/components/schemas/Alvys.Models.Trips.DateTimeWindowDto'
nullable: true
ScheduleType:
type: string
LoadingType:
type: string
nullable: true
Id:
type: string
Address:
allOf:
- $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
nullable: true
Coordinates:
allOf:
- $ref: '#/components/schemas/Alvys.Models.Coordinates'
nullable: true
Status:
type: string
nullable: true
StopType:
type: string
ArrivedAt:
type: string
format: date-time
nullable: true
DepartedAt:
type: string
format: date-time
nullable: true
References:
type: array
items:
$ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse'
CompanyId:
type: string
nullable: true
CompanyNumber:
type: string
nullable: true
CompanyName:
type: string
nullable: true
additionalProperties: false
Alvys.Models.Trips.WaypointStopResponse:
required:
- $type
- Id
- References
- StopType
type: object
properties:
StopWindow:
allOf:
- $ref: '#/components/schemas/Alvys.Models.Trips.DateTimeWindowDto'
nullable: true
Id:
type: string
Address:
allOf:
- $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
nullable: true
Coordinates:
allOf:
- $ref: '#/components/schemas/Alvys.Models.Coordinates'
nullable: true
Status:
type: string
nullable: true
StopType:
type: string
ArrivedAt:
type: string
format: date-time
nullable: true
DepartedAt:
type: string
format: date-time
nullable: true
References:
type: array
items:
$ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse'
CompanyId:
type: string
nullable: true
CompanyNumber:
type: string
nullable: true
CompanyName:
type: string
nullable: true
$type:
enum:
- waypoint
type: string
description: Type discriminator for polymorphic serialization
additionalProperties: false
Alvys.Features.Locations.ShortAddress:
required:
- City
- State
- Street
- ZipCode
type: object
properties:
Street:
type: string
City:
type: string
State:
type: string
ZipCode:
type: string
additionalProperties: false
Alvys.Models.Coordinates:
required:
- Latitude
- Longitude
type: object
properties:
Latitude:
type: string
Longitude:
type: string
additionalProperties: false
Alvys.Models.References.ReferenceResponse:
required:
- Name
- Value
type: object
properties:
Id:
type: string
nullable: true
ReferenceId:
type: string
nullable: true
Name:
type: string
Value:
type: string
Type:
type: string
nullable: true
Access:
type: string
nullable: true
Origin:
type: string
nullable: true
additionalProperties: false
Alvys.Models.Trips.DateTimeWindowDto:
required:
- Begin
- End
type: object
properties:
Begin:
type: string
format: date-time
End:
type: string
format: date-time
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 `.
````