Search outbound visibility errors

POST

api

{version}

visibility

outbound

errors

Search outbound visibility errors

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "Page": 123,
  "PageSize": 123,
  "TimeRange": {
    "Start": "2023-11-07T05:31:56Z",
    "End": "2023-11-07T05:31:56Z"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    Page: 123,
    PageSize: 123,
    TimeRange: {Start: '2023-11-07T05:31:56Z', End: '2023-11-07T05:31:56Z'}
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors"

payload = {
    "Page": 123,
    "PageSize": 123,
    "TimeRange": {
        "Start": "2023-11-07T05:31:56Z",
        "End": "2023-11-07T05:31:56Z"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'Page' => 123,
    'PageSize' => 123,
    'TimeRange' => [
        'Start' => '2023-11-07T05:31:56Z',
        'End' => '2023-11-07T05:31:56Z'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors"

	payload := strings.NewReader("{\n  \"Page\": 123,\n  \"PageSize\": 123,\n  \"TimeRange\": {\n    \"Start\": \"2023-11-07T05:31:56Z\",\n    \"End\": \"2023-11-07T05:31:56Z\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Page\": 123,\n  \"PageSize\": 123,\n  \"TimeRange\": {\n    \"Start\": \"2023-11-07T05:31:56Z\",\n    \"End\": \"2023-11-07T05:31:56Z\"\n  }\n}")
  .asString();

{
  "Page": 123,
  "PageSize": 123,
  "Total": 123,
  "Items": [
    {
      "Id": "<string>",
      "EventType": "Location",
      "SharedAt": "2023-11-07T05:31:56Z",
      "Destination": "<string>",
      "Status": "Completed",
      "ExternalId": "<string>",
      "TripNumber": "<string>",
      "LoadNumber": "<string>",
      "TruckNumber": "<string>",
      "DriverName": "<string>",
      "TrailerNumber": "<string>",
      "StopId": "<string>",
      "LocationId": "<string>",
      "SharedBy": "<string>",
      "Reason": "<string>",
      "Address": {
        "Street": "<string>",
        "City": "<string>",
        "State": "<string>",
        "ZipCode": "<string>",
        "Country": "<string>"
      },
      "Coordinates": {
        "Latitude": "<string>",
        "Longitude": "<string>"
      },
      "Error": "<string>"
    }
  ],
  "Facets": {}
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

This endpoint allows you to retrieve a paginated list of outbound errors for a specified time range. The request includes parameters for pagination and a time range filter. Note that the time range must be 7 days or less. This feature helps users identify and manage any errors that occurred while sharing updates with external systems.

Request Body Parameters

All the following parameters are required in the request body:

Parameter	Type	Required	Description
Page	Number	Yes	The page number to retrieve.
PageSize	Number	Yes	The number of items to retrieve per page.
TimeRange	Object	Yes	The time range filter for retrieving errors. Must be 7 days or less.
TimeRange.Start	String (Date-Time)	Yes	The start date and time for the time range.
TimeRange.End	String (Date-Time)	Yes	The end date and time for the time range.

Example CURL Request

curl --location 'https://integrations.alvys.com/api/p/v1/visibility/outbound/errors' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Page": 0,
    "PageSize": 10,
    "TimeRange": {
        "Start": "2024-11-11T15:15:13.876Z",
        "End": "2024-11-18T15:15:13.876Z"
    }
}'

Replace YOUR_ACCESS_TOKEN with your actual Bearer token. Ensure that the start and end dates are within a 7-day range.

Validation errors

TimeRange is required. If the request body omits it, the endpoint returns 400 Bad Request and names the missing field in the validation message: TimeRange is required. If TimeRange spans more than 7 days, the endpoint returns 400 Bad Request with the validation message Time range must be less than 7 days.

Response Fields

The response is a paginated list of error items, including details about each error:

Field	Type	Description
Page	Number	The current page number.
PageSize	Number	The number of items per page.
Total	Number	The total number of error items.
Items	Array	A list of error items.
Items.Id	String	The unique identifier of the error.
Items.ExternalId	String	The external ID related to the error.
Items.TripNumber	String	The trip number linked to the load.
Items.LoadNumber	String	The load number for which the error occurred.
Items.EventType	String	The type of event, typically “Location”.
Items.SharedAt	String (Date-Time)	The date and time when the update was shared.
Items.Destination	String	The destination of the load.
Items.TruckNumber	String	The number of the truck transporting the load.
Items.DriverName	String	The name of the driver.
Items.TrailerNumber	String	The number of the trailer being used.
Items.StopId	String	The ID of the stop related to the error.
Items.LocationId	String	The ID of the location associated with the error.
Items.SharedBy	String	The entity (user or system) that shared the update.
Items.Reason	String	The reason for the error, if provided. There is defined list on system, depending on integration. E.g.: NS - Normal Status.
Items.Address	Object	The address details of the location update.
Items.Address.Street	String	The street of the location.
Items.Address.City	String	The city of the location.
Items.Address.State	String	The state of the location.
Items.Address.ZipCode	String	The postal code of the location.
Items.Coordinates	Object	The geographic coordinates of the location.
Items.Coordinates.Latitude	String	The latitude of the location.
Items.Coordinates.Longitude	String	The longitude of the location.
Items.Status	String	The status of the update (e.g., “Completed”, “Failed”).
Items.Error	String	The error message related to the update.

Example Response

{
  "Page": 0,
  "PageSize": 10,
  "Total": 1,
  "Items": [
    {
      "Id": "9b834b4c77124b8f8f0d97b56b7dabc4",
      "ExternalId": "EXT-003",
      "TripNumber": "TRIP67890",
      "LoadNumber": "LOAD67890",
      "EventType": "Location",
      "SharedAt": "2024-11-11T15:15:13.896Z",
      "Destination": "Chicago, IL",
      "TruckNumber": "TRK67890",
      "DriverName": "Alex Johnson",
      "TrailerNumber": "TRL67890",
      "StopId": "STOP003",
      "LocationId": "LOC003",
      "SharedBy": null,
      "Reason": "NS", //normal status
      "Address": {
        "Street": "789 Oak St",
        "City": "Chicago",
        "State": "IL",
        "ZipCode": "60601"
      },
      "Coordinates": {
        "Latitude": "41.878113",
        "Longitude": "-87.629799"
      },
      "Status": "Failed",
      "Error": "EDI|Failed to send message to General Mills via EDI. Please try again or reach out to support if the problem persist."
    }
  ]
}

Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section. This page is interactive, allowing you to test the endpoint by providing the required request body. The CURL command will update automatically based on your inputs. You can also try this request by forking our Public API Postman Collection. Remember to authorize yourself before trying a request.

Authorizations

Authorization

string

header

required

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

Path Parameters

version

string

default:1.0

required

API version (e.g., 1.0)

Example:

"1.0"

Body

Page

integer<int32>

required

PageSize

integer<int32>

required

TimeRange

object

required

Show child attributes

Response

Page

integer<int32>

required

PageSize

integer<int32>

required

Total

integer<int64>

required

Items

object[]

required

Show child attributes

Facets

object | null

Show child attributes

Search outbound visibility errors

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "Page": 123,
  "PageSize": 123,
  "TimeRange": {
    "Start": "2023-11-07T05:31:56Z",
    "End": "2023-11-07T05:31:56Z"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    Page: 123,
    PageSize: 123,
    TimeRange: {Start: '2023-11-07T05:31:56Z', End: '2023-11-07T05:31:56Z'}
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors"

payload = {
    "Page": 123,
    "PageSize": 123,
    "TimeRange": {
        "Start": "2023-11-07T05:31:56Z",
        "End": "2023-11-07T05:31:56Z"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'Page' => 123,
    'PageSize' => 123,
    'TimeRange' => [
        'Start' => '2023-11-07T05:31:56Z',
        'End' => '2023-11-07T05:31:56Z'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors"

	payload := strings.NewReader("{\n  \"Page\": 123,\n  \"PageSize\": 123,\n  \"TimeRange\": {\n    \"Start\": \"2023-11-07T05:31:56Z\",\n    \"End\": \"2023-11-07T05:31:56Z\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/visibility/outbound/errors")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Page\": 123,\n  \"PageSize\": 123,\n  \"TimeRange\": {\n    \"Start\": \"2023-11-07T05:31:56Z\",\n    \"End\": \"2023-11-07T05:31:56Z\"\n  }\n}")
  .asString();

{
  "Page": 123,
  "PageSize": 123,
  "Total": 123,
  "Items": [
    {
      "Id": "<string>",
      "EventType": "Location",
      "SharedAt": "2023-11-07T05:31:56Z",
      "Destination": "<string>",
      "Status": "Completed",
      "ExternalId": "<string>",
      "TripNumber": "<string>",
      "LoadNumber": "<string>",
      "TruckNumber": "<string>",
      "DriverName": "<string>",
      "TrailerNumber": "<string>",
      "StopId": "<string>",
      "LocationId": "<string>",
      "SharedBy": "<string>",
      "Reason": "<string>",
      "Address": {
        "Street": "<string>",
        "City": "<string>",
        "State": "<string>",
        "ZipCode": "<string>",
        "Country": "<string>"
      },
      "Coordinates": {
        "Latitude": "<string>",
        "Longitude": "<string>"
      },
      "Error": "<string>"
    }
  ],
  "Facets": {}
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

​Request Body Parameters

​Example CURL Request

​Validation errors

​Response Fields

​Example Response

​Rate Limits

Authorizations

Path Parameters

Body

Response

Request Body Parameters

Example CURL Request

Validation errors

Response Fields

Example Response

Rate Limits