POST - Position Event

The PositionEvent Services comprises a collection of several Objects that ultimately allow users to create and retrieve PositionEvents for shipments within the Freight Portal.

In order to get started. you'll have to create a Basic PositionEvent Object. The following guides below, help you create (POST) and retrieve (GET) a PositionEvent for a shipment.

POST - Position Event

The POST position endpoint allows the tracking of a specific shipment in the Freight Portal.

The POST position endpoint has multiple parameter values that can be included in the object. As a base level requirement, the following Objects are required in order to successfully create a position event:

1. PositionEvent Object

Posting a Postion Event

The POST HTTP Endpoint for position event creation is listed below:

HTTP Verb: POST
URI: /atlas/frexapi/shipment/position
Authentication: Validation Through Request Parameters

To create a position event, the following fields are required:

1. TenFourLicensePlate
or
2. FreightProviderReferenceNumber and FreightHaulerProviderXID

Parameter	Type	Description
FreightProviderReferenceNumber	String	The external reference number of the shipper's given shipment (BOL).
FreightHaulerProviderXID	String	10-4's external reference id between a shipper and a carrier.
TenFourLicensePlate	String	The external reference number of the shipper's given shipment (BOL).

Adding the Carrier

Next, in order to tie a shipment to a specific carrier, you'll need to supply one of the following carrier identification parameters listed below:

Parameter	Type	Description
CarrierMC	String	The external reference to the carrier's MC-Number.
CarrierDOT	String	The external reference to the carrier's USDOT-Number.
CarrierSCAC	String	The external reference to the carrier's SCAC.

Adding Position Event Location Data

To have the PositionEvent Object validate properly, you must supply a method to infer the physical location of the shipment. Below are the two examples of what you may choose from and their respected parameters, data types, and descriptions.

Parameter	Type	Description
Latitude	Decimal	Latitude of the shipment's stop. Can be up to 6 decimal places long.
Longitude	Decimal	Longitude of the shipment's stop. Can be up to 6 decimal places long.
StreetAddress1	String	Street address of the stop. Max Length: 500.
City	String	City of the stop.
State	String	State of the stop.
PostalCode	String	PostalCode of the stop.
Country	String	Country of the stop.

Adding Other Required Position Event Parameters

For positional data to be successfully validated, a type and time must be passed through the PositionEvent Object. The following fields are required:

Parameter	Type	Description
PositionEventType	Enumeration	Enumeration type of the given position event.
PositionReportTime	DateTimeOffset	DateTime of the position event.

Completed PositionEvent Object

Here is an example of a completely valid basic shipment JSON Object using either Lat/Long or a street address:

{
  "FreightProviderReferenceNumber":"12345670",
  "FreightHaulerProviderXID":"ABD3820AI",
  "CarrierMC":"3829182",
  "Latitude":40.0150,
  "Longitude":-105.2705,
  "PositionEventType":3,
  "PositionReportTime": "2017-03-20T17:52:22"
}

{
  "FreightProviderReferenceNumber":"12345670",
  "FreightHaulerProviderXID":"ABD3820AI",
  "CarrierMC":"3829182",
  "StreetAddress1":"4750 W MOHAVE ST",
  "City":"PHOENIX",
  "PostalCode":"85043",
  "State":"AZ",
  "Country":"US",
  "PositionEventType":3,
  "PositionReportTime": "2017-03-20T17:52:22"
}

Success response is 200

Updated about 2 months ago

What’s Next

[OPTIONAL] Temperature Data