--- title: "Initialize a shipment for tracking." method: POST path: "/api/v4/rail/shipments" tags: ["Rail: Tracking"] --- # Initialize a shipment for tracking. `POST /api/v4/rail/shipments` ## Request - Base URL: `https://na12.api.project44.com` - URL: `https://na12.api.project44.com/api/v4/rail/shipments` - Auth: OAuth 2 - Client credentials - Token URL: `/api/v4/oauth2/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) If the shipment is initialized by using geoCoordinates instead of an address, it may be possible that a street address will not be returned in the response.

Required Fields

## Request body - RailShipment - `equipmentIdentifiers` RailEquipmentIdentifier[]: A user-defined list of equipment identifiers identifying rail equipment to be tracked as part of this shipment. This includes container ids and rail car ids. A rail shipment may only have 1 equipment identifier - `type` 'CONTAINER_ID' | 'TRAILER_ID' | 'RAIL_CAR_ID': The type of the equipment identifier. - `value` string: The value of the equipment identifier. - `id` integer: DEPRECATED: The project44-generated id for the rail shipment. This may not be provided when creating a shipment, but will always be returned in the shipment confirmation. This id may be used in subsequent API calls to reference a shipment. This field is deprecated, use railLegId instead. - `masterShipmentId` string, uuid: This id links 1 or more legs as part of the same overall shipment. For intermodal shipments, pass an existing masterShipmentId to link this rail leg to the overall master shipment. Otherwise pass any valid new UUID to create a new shipment. If no masterShipmentId is passed on POST request a new UUID will be generated. This value will always be returned on all responses. - `railLegId` string, uuid: Identifies the leg of the journey. Each piece of equipment has a unique id for each mode that it travels on.This id may be used in subsequent API calls to reference this shipment leg. - `shipmentIdentifiers` RailShipmentIdentifier[]: A user-defined list of shipment identifiers that are unique to this shipment. You must pass in either a shipment identifier or a tracking start date time. - `type` 'BILL_OF_LADING' | 'WAYBILL': The type of the shipment identifier. - `value` string: The value of the shipment identifier. - `shipmentStops` RailShipmentStop[]: Contains the shipment's origin and destination. - `appointmentWindow` ZonedDateTimeWindow: A date and time range, including a time zone, representing a window of availability. - `endDateTime` string, date-time: End date and time of this window in the applicable time zone. (format: yyyy-MM-dd'T'HH:mm:ss) - `localTimeZoneIdentifier` string: The time zone identifier (e.g., 'America/Chicago') for this date time window. - `startDateTime` string, date-time: Start date and time of this window in the applicable time zone.(default: current date, format: yyyy-MM-dd'T'HH:mm:ss) - `geoCoordinates` GeoCoordinates - `latitude` number, float: The approximate geographic latitude of a location, using the WGS84 coordinate system. - `longitude` number, float: The approximate geographic longitude of a location, using the WGS84 coordinate system. - `id` string, uuid: Project44 defined stop id. Always returned on response. - `location` RailLocation: A physical location. - `address` RailAddress: A postal address. - `pointName` string: Name of this point. Usually a city name but may also be the name of the junction, yard, or facility - `state` string: Abbreviation of state, province, district, etc. - `id` string: The project44-generated id for this location. - `stopName` string: The optionally user-defined stop name of this stop. This is a freeform field. If no name is provided Project44 will default the name of each stop based on the address or stop number. - `stopNumber` integer: The user-defined stop number, where '1' is the origin and '2' is the destination. - `type` 'UNKNOWN' | 'ORIGIN' | 'DESTINATION' | 'TRANSFER' | 'OTHER' | 'PORT_OF_LOADING' | 'TRANSSHIPMENT_PORT' | 'PORT_OF_DISCHARGE' | 'PICKUP' | 'DELIVERY' | 'RETURN' | 'WAREHOUSE' | 'HUB' | 'AIRPORT': How this stop relates to the shipment. This field must be null or absent when creating a shipment. The stop type will be determined by project44. - `trackingStartDateTime` string: Tracking for this shipment will begin at this time. This should be set to the time when your shipment has been loaded into the container or rail car. Cannot be more than 90 days in the past or 90 days in the future. You must pass in either a shipment identifier or a tracking start date time. ## Response `200` OK - RailShipmentConfirmation - `infoMessages` Message[]: System messages and messages from the capacity provider with severity 'INFO' or 'WARNING'. No messages with severity 'ERROR' will be returned here. - `diagnostic` string: Diagnostic information, often originating from the capacity provider. - `message` string: Message informational text. - `severity` 'ERROR' | 'WARNING' | 'INFO': The severity of this message. - `source` 'SYSTEM' | 'CAPACITY_PROVIDER': The originator of this message -- either project44 (the system) or the capacity provider. - `shipment` RailShipment - `equipmentIdentifiers` RailEquipmentIdentifier[]: A user-defined list of equipment identifiers identifying rail equipment to be tracked as part of this shipment. This includes container ids and rail car ids. A rail shipment may only have 1 equipment identifier - `type` 'CONTAINER_ID' | 'TRAILER_ID' | 'RAIL_CAR_ID': The type of the equipment identifier. - `value` string: The value of the equipment identifier. - `id` integer: DEPRECATED: The project44-generated id for the rail shipment. This may not be provided when creating a shipment, but will always be returned in the shipment confirmation. This id may be used in subsequent API calls to reference a shipment. This field is deprecated, use railLegId instead. - `masterShipmentId` string, uuid: This id links 1 or more legs as part of the same overall shipment. For intermodal shipments, pass an existing masterShipmentId to link this rail leg to the overall master shipment. Otherwise pass any valid new UUID to create a new shipment. If no masterShipmentId is passed on POST request a new UUID will be generated. This value will always be returned on all responses. - `railLegId` string, uuid: Identifies the leg of the journey. Each piece of equipment has a unique id for each mode that it travels on.This id may be used in subsequent API calls to reference this shipment leg. - `shipmentIdentifiers` RailShipmentIdentifier[]: A user-defined list of shipment identifiers that are unique to this shipment. You must pass in either a shipment identifier or a tracking start date time. - `type` 'BILL_OF_LADING' | 'WAYBILL': The type of the shipment identifier. - `value` string: The value of the shipment identifier. - `shipmentStops` RailShipmentStop[]: Contains the shipment's origin and destination. - `appointmentWindow` ZonedDateTimeWindow: A date and time range, including a time zone, representing a window of availability. - `endDateTime` string, date-time: End date and time of this window in the applicable time zone. (format: yyyy-MM-dd'T'HH:mm:ss) - `localTimeZoneIdentifier` string: The time zone identifier (e.g., 'America/Chicago') for this date time window. - `startDateTime` string, date-time: Start date and time of this window in the applicable time zone.(default: current date, format: yyyy-MM-dd'T'HH:mm:ss) - `geoCoordinates` GeoCoordinates - `latitude` number, float: The approximate geographic latitude of a location, using the WGS84 coordinate system. - `longitude` number, float: The approximate geographic longitude of a location, using the WGS84 coordinate system. - `id` string, uuid: Project44 defined stop id. Always returned on response. - `location` RailLocation: A physical location. - `address` RailAddress: A postal address. - `pointName` string: Name of this point. Usually a city name but may also be the name of the junction, yard, or facility - `state` string: Abbreviation of state, province, district, etc. - `id` string: The project44-generated id for this location. - `stopName` string: The optionally user-defined stop name of this stop. This is a freeform field. If no name is provided Project44 will default the name of each stop based on the address or stop number. - `stopNumber` integer: The user-defined stop number, where '1' is the origin and '2' is the destination. - `type` 'UNKNOWN' | 'ORIGIN' | 'DESTINATION' | 'TRANSFER' | 'OTHER' | 'PORT_OF_LOADING' | 'TRANSSHIPMENT_PORT' | 'PORT_OF_DISCHARGE' | 'PICKUP' | 'DELIVERY' | 'RETURN' | 'WAREHOUSE' | 'HUB' | 'AIRPORT': How this stop relates to the shipment. This field must be null or absent when creating a shipment. The stop type will be determined by project44. - `trackingStartDateTime` string: Tracking for this shipment will begin at this time. This should be set to the time when your shipment has been loaded into the container or rail car. Cannot be more than 90 days in the past or 90 days in the future. You must pass in either a shipment identifier or a tracking start date time. ## Other responses - `400`: Invalid request - `401`: Invalid or missing credentials - `403`: User not authorized to perform this operation --- [API](https://skmtc.dev/project44/apis/project44-rest-api.md) - [All operations](https://skmtc.dev/project44/apis/project44-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/project44/apis/project44-rest-api/revisions/cdf9675e2294?raw)