> ## 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 asset location
> Record where a driver, truck, or trailer is from a third-party source, so partner telematics data drives Alvys load and asset tracking alongside first-party ELD feeds.
Records where an asset is — position, and optionally the odometer. Use this when an external system knows an asset's location: a third-party ELD, or a vehicle reporting its own position.
To send speed, fuel, or temperature readings taken at the same moment, use [Record asset telemetry](/en/api/reference/visibility/record-asset-telemetry) instead. This endpoint is position-only by design.
This endpoint requires the `visibility:create` scope. See [Authentication](/en/api/guides/authentication-1).
`assetId` is the Alvys id of a driver, truck, or trailer — the `Id` returned by the [drivers](/en/api/reference/drivers/list-drivers), [trucks](/en/api/reference/trucks/list-trucks), and [trailers](/en/api/reference/trailers/list-trailers) endpoints. It is **not** a unit number.
### Ordering and duplicate readings
Positions are ordered per asset by `RecordedAt`. A reading older than, or equal to, the one already held for this source is discarded and answered `409 Conflict`.
A `409` is a normal out-of-order outcome, not a failure. **Do not retry it** — resending the same reading will keep answering `409`. Send the next reading instead.
This also makes retries safe: resending a reading you already delivered does not move the asset or fire a duplicate tracking update.
### Endpoint
```
POST /api/p/v{version}/assets/{assetId}/locations
```
### Request Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| version | string | Yes | API version to use (`1.0`). |
| assetId | string | Yes | Alvys id of the driver, truck, or trailer. Not a unit number. |
### Request Body
| Field | Type | Required | Description |
| --------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| Coordinates | Object | Yes | Where the asset is. A missing, out-of-range, or `(0, 0)` value is rejected with `400`. |
| Coordinates.Latitude | string | Yes | Latitude, as a string. |
| Coordinates.Longitude | string | Yes | Longitude, as a string. |
| RecordedAt | string (datetime) | No | When the reading was taken, ISO-8601. Defaults to the time Alvys receives it. Positions are ordered by this field. |
| Address | Object | No | `Street`, `City`, `State`, `ZipCode`, `Country`. Omit it and Alvys resolves an address from the coordinates. |
| TripId | string | No | The trip to attribute the reading to. Omit it and Alvys selects the asset's active trip with the nearest stop. |
| Odometer | number | No | Odometer reading in miles. |
| OdometerReadingAt | string (datetime) | No | When the odometer was read, ISO-8601. |
Pass `TripId` when you know it. On an asset running more than one active trip — a team, drop-and-hook, or multi-stop asset — Alvys otherwise picks the trip with the nearest stop, and the tracking update, ETA, and customer tracking page follow that choice.
The request body is limited to 8 KB. Send one reading per request.
### Example Request Body
```json theme={null}
{
"Coordinates": {
"Latitude": "32.7767",
"Longitude": "-96.7970"
},
"RecordedAt": "2026-08-21T14:32:00Z",
"Odometer": 154302.5,
"OdometerReadingAt": "2026-08-21T14:32:00Z"
}
```
### Example CURL request
```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/assets/{assetId}/locations' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"Coordinates": {
"Latitude": "32.7767",
"Longitude": "-96.7970"
},
"RecordedAt": "2026-08-21T14:32:00Z",
"Odometer": 154302.5,
"OdometerReadingAt": "2026-08-21T14:32:00Z"
}'
```
### Response Fields
| Field | Type | Description |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------- |
| AssetId | string | Alvys id of the asset. |
| AssetType | string | `Driver`, `Truck`, or `Trailer`. |
| Source | string | Tracking source. Always `PublicApi` for positions submitted through this endpoint. |
| Coordinates.Latitude | string | Latitude of the recorded position. |
| Coordinates.Longitude | string | Longitude of the recorded position. |
| Address | Object | The address you supplied, or the one resolved from the coordinates. |
| FormattedAddress | string | That address as a single display string. |
| RecordedAt | string (datetime) | Observation time the position is ordered by. |
| ReceivedAt | string (datetime) | When Alvys accepted the position. |
| TripId | string | The asset's trip at the time of the reading, if any. |
| TripNumber | string | Number of that trip, if any. |
| Odometer | number | Odometer reading in miles, as reported. |
| OdometerReadingAt | string (datetime) | When the odometer was read, as reported. |
### Example Response
**201 Created**
```json theme={null}
{
"AssetId": "TR2517179655771527026",
"AssetType": "Truck",
"Source": "PublicApi",
"Coordinates": {
"Latitude": "32.7767",
"Longitude": "-96.7970"
},
"Address": {
"Street": "201 Main St",
"City": "Dallas",
"State": "TX",
"ZipCode": "75201",
"Country": "US"
},
"FormattedAddress": "201 Main St, Dallas, TX 75201",
"RecordedAt": "2026-08-21T14:32:00Z",
"ReceivedAt": "2026-08-21T14:32:04Z",
"TripId": "9d4b1327-2774-d32c-fb33-87a288c2722c",
"TripNumber": "T-100234",
"Odometer": 154302.5,
"OdometerReadingAt": "2026-08-21T14:32:00Z"
}
```
### Status Codes
| Status | Description |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 201 | Position recorded. |
| 400 | Invalid body — missing, out-of-range, or `(0, 0)` coordinates, or a malformed field. |
| 401 | Missing or invalid access token. |
| 403 | Token lacks the `visibility:create` scope. |
| 404 | Asset not found, or outside your credential's subsidiary scope. |
| 409 | A newer position is already recorded for this asset from this source. The reading was discarded. Do not retry. |
| 422 | `RecordedAt` is more than 5 minutes ahead of the server clock. A future-dated reading would suppress every later position for this asset until real time caught up. |
| 429 | Rate limit exceeded. |
A `409` carries the error type `https://api.alvys.com/errors/Conflict/StaleLocation` and reports the `RecordedAt` of the position currently held, so you can tell how far behind your feed is.
### Rate Limits
All endpoints are subject to rate limits to protect the API from traffic spikes. See [Rate Limits](/en/api/guides/rate-limits).
## OpenAPI
````yaml POST /api/p/v{version}/assets/{assetId}/locations
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: Subsidiaries
description: >-
List your company's subsidiaries and read a single subsidiary, so an
integration can resolve a subsidiary id to a recognizable name.
- name: Tenders
description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
- name: Tolls
description: Read and search toll transactions.
- name: Tracking
description: >-
Record an asset's current location or telemetry from a third-party source,
such as an external ELD or a self-reporting vehicle.
- 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}/assets/{assetId}/locations:
post:
tags:
- Tracking
summary: Record an asset's current location
description: >-
Records where an asset is — position and optionally the odometer. To
send speed, fuel or temperature readings taken at the same moment, use
the telemetry endpoint instead. Positions are ordered per asset by
RecordedAt: a reading older than the one already held for this source is
discarded and reported as 409 Conflict, which is a normal out-of-order
outcome and must not be retried. The asset id is the Alvys id of a
driver, truck or trailer (as returned by the drivers, trucks and
trailers endpoints — not a unit number).
parameters:
- name: assetId
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.Tracking.Public.AssetLocationCreateRequest
application/json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Tracking.Public.AssetLocationCreateRequest
text/json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Tracking.Public.AssetLocationCreateRequest
application/*+json:
schema:
allOf:
- $ref: >-
#/components/schemas/Alvys.Models.Tracking.Public.AssetLocationCreateRequest
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: >-
#/components/schemas/Alvys.Models.Tracking.Public.AssetLocationResponse
'400':
description: Bad Request
content:
application/json:
schema:
$ref: >-
#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
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'
'409':
description: Conflict
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/json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
security:
- Public: []
components:
schemas:
Alvys.Models.Tracking.Public.AssetLocationCreateRequest:
type: object
properties:
Coordinates:
allOf:
- $ref: '#/components/schemas/Alvys.Models.Coordinates'
nullable: true
RecordedAt:
type: string
format: date-time
nullable: true
Address:
allOf:
- $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
nullable: true
TripId:
type: string
nullable: true
Odometer:
type: number
format: double
nullable: true
OdometerReadingAt:
type: string
format: date-time
nullable: true
additionalProperties: false
Alvys.Models.Tracking.Public.AssetLocationResponse:
required:
- AssetId
- AssetType
- Coordinates
- ReceivedAt
- RecordedAt
- Source
type: object
properties:
AssetId:
type: string
AssetType:
type: string
Source:
type: string
Coordinates:
allOf:
- $ref: '#/components/schemas/Alvys.Models.Coordinates'
Address:
allOf:
- $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
nullable: true
FormattedAddress:
type: string
nullable: true
RecordedAt:
type: string
format: date-time
ReceivedAt:
type: string
format: date-time
TripId:
type: string
nullable: true
TripNumber:
type: string
nullable: true
Odometer:
type: number
format: double
nullable: true
OdometerReadingAt:
type: string
format: date-time
nullable: true
additionalProperties: false
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.Coordinates:
required:
- Latitude
- Longitude
type: object
properties:
Latitude:
type: string
Longitude:
type: string
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
Country:
type: string
description: >-
ISO 3166-1 alpha-2 country code where the recorded value is a
recognized spelling of United States, Canada or Mexico; otherwise
the country exactly as recorded, which for addresses created before
this field existed may be any string. Omitted when no country is
recorded; an absent Country must NOT be interpreted as US.
nullable: true
additionalProperties: false
securitySchemes:
Public:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
OAuth 2.0 client-credentials access token. Obtain one from
https://auth.alvys.com/oauth/token (grant_type=client_credentials,
audience=https://api.alvys.com/public/), then paste it here. The
playground sends it as `Authorization: Bearer `.
````