> ## 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.

# Record stop arrival

> 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.

This endpoint marks the stop as **arrived** and updates the stop’s `ArrivedAt` timestamp.\
The `ArrivedAt` field is required and must contain a valid ISO-8601 UTC datetime.

The response returns the **updated stop object**.

***

### Endpoint

```
PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
```

***

### 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                                   |
| --------- | ----------------- | -------- | --------------------------------------------- |
| ArrivedAt | string (datetime) | Yes      | Arrival timestamp in **ISO-8601 UTC format**. |

***

### Example Request Body

```json theme={null}
{
  "ArrivedAt": "2026-03-16T12:34:30.277Z"
}
```

***

### Example CURL request

```bash theme={null}
curl --location --request PUT 'https://integrations.alvys.com/api/p/v1/trips/{tripId}/stops/{stopId}/arrival' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "ArrivedAt": "2026-03-16T12:34:30.277Z"
}'
```

***

### 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 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.                                         |
| 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:34:30.277Z",
  "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:34:30.277Z",
  "DepartedAt": "2026-03-16T12:34:30.277Z",
  "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 arrival successfully recorded.       |
| 400 Bad Request | Invalid request body or timestamp format. |
| 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}/arrival
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}/arrival:
    put:
      tags:
        - Trips
      summary: Record stop arrival
      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.RecordArrivalRequest
          application/json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Trips.Request.RecordArrivalRequest
          text/json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Trips.Request.RecordArrivalRequest
          application/*+json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Trips.Request.RecordArrivalRequest
      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'
        '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.RecordArrivalRequest:
      required:
        - ArrivedAt
      type: object
      properties:
        ArrivedAt:
          type: string
      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 <token>`.

````