Create a Shipment

Create a Rail shipment to initalize the shipment for tracking. There are different requirements for creating a rail shipment based on region (North America or Europe) and number of stops (this is specific to EU rail shipments only). These requirements are indicated in each use case below.

Create a North America Rail Shipment

Create a North America Rail shipment to be tracked in project44's network. This step is necessary before tracking of a Rail shipment can start.

Requirements

Have the following information, at a minimum, to successfully create a shipment:

Shipment identifier (CONTAINER_ID, TRAILER_ID, or RAIL_CAR_ID)

Workflow

Prepare a POST request to /api/v4/shipments/tracking. For example:

{
    "identifiers": [
        {
            "type": "TRAILER_ID",
            "value": "string"
        }
    ]
}

This only shows the minimum required request schema to create a North America rail shipment . To view the full request schema, see the API Reference documentation for this endpoint.

Send the request.

Fields and Objects

Element	Description	Type	Notes
`identifiers`	A list of the shipment's identifying information.	`array` of identifiers
`identifiers.type`	The type of shipment identifier.	`string`	Valid values include: `CONTAINER_ID`, `TRAILER_ID`, or `RAIL_CAR_ID`.
`identifiers.value`	The value of the shipment identifier.	`string`

Expected System Response

You have successfully submitted the request when you receive a 200 OK response.

{
  "id": "string",
  "identifiers": [
    {
      "type": "TRAILER_ID",
      "value": "string"
    }
  ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the API Reference documentation for more information on required and potential null fields.

A unique project44 ID (id) is returned in the response after shipment creation. Store this ID to use in future API calls.

Fields and Objects

Element	Description	Type	Notes
`id`	The shipment's master shipment ID.	`string`	The `id` will always be populated in the `POST` response. The `id` will always be populated in the `POST` response. Save this Shipment ID and use for future API calls.
`identifiers`	A list of the shipment's identifying information.	Array of identifiers
`identifiers.type`	The type of shipment identifier.	`string`	Valid values for North American Rail identifiers include: `CONTAINER_ID`, `TRAILER_ID`, or `RAIL_CAR_ID`.
`identifiers.value`	The value of the shipment identifier.	`string`

Errors

If there was a problem with your request, you will receive one of the following error codes

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Create a Europe Rail Shipment with One Stop

Create a Europe Rail shipment with stop information that includes the running country or the start station. This step is necessary before tracking of a Rail shipment can start.

Requirements

Have the following information, at a minimum, to successfully create a shipment:

Shipment identifier (TRAIN_NUMBER)
Information for the ORIGIN or DESTINATION stop, including the country code
Events with planned times

Workflow

Prepare a POST request to /api/v4/shipments/tracking. For example:

{
    "identifiers": [
        {
            "type": "TRAIN_NUMBER",
            "value": "string"
        }
    ],
    "routeInfo": {
        "stops": [
            {
                "id": "string",
                "type": "ORIGIN",
                "location": {   
                    "address": {
                        "country": "IT"
                        }    
                }
            }
        ]
    },
    "events": [
        {
            "type": "DEPARTURE_FROM_STOP",
            "stopId": "string",
            "plannedDateTime": "2022-10-01T04:00:00+0000"
        }
    ]
}

This only shows the minimum required request schema to create a Europe rail shipment with one stop. To view the full request schema, see the API Reference documentation for this endpoint.

Send the request.

Fields and Objects

Element	Description	Type	Notes
`identifiers`	A list of the shipment's identifying information.	Array of identifiers
`identifiers.type`	The type of shipment identifier.	`string`	Valid value is `TRAIN_NUMBER`.
`identifiers.value`	The value of the shipment identifier.	`string`
`routeInfo`	An object of information for one stop.	`object`
`routeInfo.stops`	An array of the stop associated with the shipment.	Array of `objects`
`routeInfo.stops.id`	The uuid for the stop.
`routeInfo.stops.type`	The type of stop.	`string`	Valid value is: `ORIGIN` or `DESTINATION`.
`routeInfo.stops.location`	The stop location object.	`object`
`routeInfo.stops.location.address`	The stop address object.	`object`	For shipments with one stop, the country code is mandatory.
`routeInfo.stops.location.address.country`	The country code for the stop location.	`string`	See the API Reference Documentation for a list of valid values.
`events`	Events for the shipment.	Array of `objects`
`events.type`	The type of event that will occur.	`string`	The event type depends on the stop type. Valid values include: `DEPARTURE_FROM_STOP` event type for an `ORIGIN` stop type.
`events.stopId`	The ID of the stop relevant to the event.	`string`
`events.plannedDateTime`	The planned time for when the event window will start.	`string`

Expected System Response

You have successfully submitted the request when you receive a 200 OK response.

{
    "id": "string",
    "identifiers": [
        {
            "type": "TRAIN_NUMBER",
            "value": "string"
        }
    ],
    "routeInfo": {
        "stops": [
            {
                "id": "string",
                "type": "ORIGIN",
                "location": {   
                    "address": {
                        "country": "IT"
                        }    
                }
            }
        ]
    },
    "events": [
        {
            "type": "DEPARTURE_FROM_STOP",
            "stopId": "string",
            "plannedDateTime": "2022-10-01T04:00:00+0000"
        }
    ]
}

A unique project44 ID (id) is returned in the response after shipment creation. Store this ID to use in future API calls.

Fields and Objects

Element	Description	Type	Notes
`id`	The shipment's master shipment ID.	`string`	The `id` will always be populated in the `POST` response. Save this Shipment ID and use for future API calls.
`identifiers`	A list of the shipment's identifying information.	Array of identifiers
`identifiers.type`	The type of shipment identifier.	`string`	Valid values for North American Rail identifiers include: `WAGON_ID` or `TRAIN_NUMBER`.
`identifiers.value`	The value of the shipment identifier.	`string`
`routeInfo`	An object of information for one stop.	`object`
`routeInfo.stops`	An array of the stop associated with the shipment.	Array of `objects`
`routeInfo.stops.id`	The uuid for the stop.
`routeInfo.stops.type`	The type of stop.	`string`	Valid value is: `ORIGIN` or `DESTINATION`.
`routeInfo.stops.location`	The stop location object.	`object`
`routeInfo.stops.location.address`	The stop address object.	`object`	For shipments with one stop, the country code is mandatory.
`routeInfo.stops.location.address.country`	The country code for the stop location.	`string`	See the API Reference Documentation for a list of valid values.
`events`	Events for the shipment.	Array of `objects`
`events.type`	The type of event that will occur.	`string`	The event type depends on the stop type. Valid values include: `DEPARTURE_FROM_STOP` event type for an `ORIGIN` stop type.
`events.stopId`	The ID of the stop relevant to the event.	`string`
`events.plannedDateTime`	The planned time for when the event window will start.	`string`

Errors

If there was a problem with your request, you will receive one of the following error codes

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Create a Europe Rail Shipment with More than One Stop

Create a Europe Rail shipment with information for more than one stop. This step is necessary before tracking of a Rail shipment can start.

Requirements

Have the following information, at a minimum, to successfully create a shipment:

Shipment identifier (WAGON_ID or TRAIN_NUMBER)
Information for each stop, including either coordinates or the station identifiers, stop type, stop name, and stop ID
Events with planned times

Workflow

Prepare a POST request to /api/v4/shipments/tracking. For example:

{
    "identifiers": [
        {
            "type": "WAGON_ID",
            "value": "string"
        }
    ],
    "routeInfo": {
        "stops": [
            {
                "id": "string",
                "type": "ORIGIN",
                "location": {
                    "identifiers": [
                        {
                            "type": "RAIL_EU_PLC",
                            "value": "string"
                        }
                    ],
                    "name": "string",
                    "address": {
                        "postalCode": "string",
                        "addressLines": [...],
                        "city": "string",
                        "state": "string",
                        "country": "US"
                    }
                }
            },
            {
                "id": "string",
                "type": "DESTINATION",
                "location": {
                    "identifiers": [
                        {
                            "type": "RAIL_EU_PLC",
                            "value": "string"
                        }
                    ],
                    "name": "string",
                    "address": {
                        "postalCode": "string",
                        "addressLines": [...],
                        "city": "string",
                        "state": "string",
                        "country": "US"
                    }
                }
            }
        ]
    },
    "events": [
        {
            "type": "DEPARTURE_FROM_STOP",
            "stopId": "string",
            "plannedDateTime": "2022-10-01T04:00:00+0000"
        },
        {
            "type": "ARRIVAL_AT_STOP",
            "stopId": "string",
            "plannedDateTime": "2022-10-01T22:00:00+0000"
        }
    ]
}

This only shows the minimum required request schema to create a European rail shipment with more than one stop. To view the full request schema, see the API Reference documentation for this endpoint.

Send the request.

Fields and Objects

Element	Description	Type	Notes
`identifiers`	A list of the shipment's identifying information.	Array of identifiers
`identifiers.type`	The type of shipment identifier.	`string`	Valid values include: `WAGON_ID` or `TRAIN_NUMBER`.
`identifiers.value`	The value of the shipment identifier.	`string`
`routeInfo`	An object of information for one stop.	`object`
`routeInfo.stops`	An array of the stop associated with the shipment.	Array of `objects`
`routeInfo.stops.id`	The ID of the stop.	`string`
`routeInfo.stops.type`	The type of stop.	`string`	Valid values include: `ORIGIN`, `DESTINATION`, or `TRANSFER`.
`routeInfo.stops.location`	The stop location object.	`object`
`routeInfo.stops.location.identifiers`	The list of standard identifiers for the location.	Array of `objects`
`routeInfo.stops.location.identifiers.type`	The type of location identifier.	`string`	Valid values include" `RAIL_SPLC`, `RAIL_UIC`, and `RAIL_EU_PLC`.
`routeInfo.stops.location.identifiers.value`	The value of the location identifier.	`string`
`routeInfo.stops.location.name`	The stop name.	`string`
`routeInfo.stops.location.address`	The stop address object.	`object`
`events`	Events for the shipment.	Array of `objects`
`events.type`	The type of event that will occur.	`string`	The event type depends on the stop type. Valid values include: `DEPARTURE_FROM_STOP` event type for an `ORIGIN` stop type. Both `ARRIVAL_AT_STOP` and `DEPARTURE_FROM_STOP` event types for a `TRANSFER` stop type `ARRIVAL_AT_STOP` event type for a `DESTINATION` stop type.
`events.stopId`	The ID of the stop relevant to the event.	`string`
`events.plannedDateTime`	The planned time for when the event window will start.	`string`

Expected System Response

You have successfully submitted the request when you receive a 200 OK response.

{
    "id": "string",
    "identifiers": [
        {
            "type": "TRAIN_NUMBER",
            "value": "string"
        }
    ],
    "shipmentShareLink": "string",
    "createdDateTime": "2022-09-09T11:54:14+0000",
    "routeInfo": {
        "stops": [
            {
                "id": "string",
                "type": "ORIGIN",
                "location": {
                    "name": "string",
                    "identifiers": [
                        {
                            "type": "RAIL_EU_PLC",
                            "value": "string"
                        }
                    ],
                    "address": {
                        "postalCode": "string",
                        "addressLines": ["object"],
                        "city": "string",
                        "state": "string",
                        "country": "US"
                    }
                }
            },
            {
                "id": "string",
                "type": "DESTINATION",
                "location": {
                    "name": "string",
                    "identifiers": [
                        {
                            "type": "RAIL_EU_PLC",
                            "value": "string"
                        }
                    ],
                    "address": {
                        "postalCode": "string",
                        "addressLines": ["object"],
                        "city": "string",
                        "state": "string",
                        "country": "US"
                    }
                }
            }
        ]
    },
    "events": [
        {
            "type": "DEPARTURE_FROM_STOP",
            "stopId": "string",
            "plannedDateTime": "2022-10-01T04:00:00+0000"
        },
        {
            "type": "ARRIVAL_AT_STOP",
            "stopId": "string",
            "plannedDateTime": "2022-10-01T22:00:00+0000"
        }
    ]
}

A unique project44 ID (id) is returned in the response after shipment creation. Store this ID to use in future API calls.

Fields and Objects

Element	Description	Type	Notes
`identifiers`	A list of the shipment's identifying information.	Array of identifiers
`identifiers.type`	The type of shipment identifier.	`string`	Valid values include: `WAGON_ID` or `TRAIN_NUMBER`.
`identifiers.value`	The value of the shipment identifier.	`string`
`routeInfo`	An object of information for one stop.	`object`
`routeInfo.stops`	An array of the stop associated with the shipment.	Array of `objects`
`routeInfo.stops.id`	The ID of the stop.	`string`
`routeInfo.stops.type`	The type of stop.	`string`	Valid values include: `ORIGIN`, `DESTINATION`, and `TRANSFER`.
`routeInfo.stops.location`	The stop location object.	`object`
`routeInfo.stops.location.identifiers`	The list of standard identifiers for the location.	Array of `objects`
`routeInfo.stops.location.identifiers.type`	The type of location identifier.	`string`	Valid values include" `RAIL_SPLC`, `RAIL_UIC`, and `RAIL_EU_PLC`.
`routeInfo.stops.location.identifiers.value`	The value of the location identifier.	`string`
`routeInfo.stops.location.name`	The stop name.	`string`
`routeInfo.stops.location.address`	The stop address object.	`object`
`events`	Events for the shipment.	Array of `objects`
`events.type`	The type of event that will occur.	`string`	The event type depends on the stop type. Valid values include: `DEPARTURE_FROM_STOP` event type for an `ORIGIN` stop type. Both `ARRIVAL_AT_STOP` and `DEPARTURE_FROM_STOP` event types for a `TRANSFER` stop type `ARRIVAL_AT_STOP` event type for a `DESTINATION` stop type.
`events.stopId`	The ID of the stop relevant to the event.	`string`
`events.plannedDateTime`	The planned time for when the event window will start.	`string`

Errors

If there was a problem with your request, you will receive one of the following error codes

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Create a Shipment

Create a North America Rail Shipment

Requirements

Workflow

Expected System Response

Errors

Create a Europe Rail Shipment with One Stop

Requirements

Workflow

Expected System Response

Errors

Create a Europe Rail Shipment with More than One Stop

Requirements

Workflow

Expected System Response

Errors

Was this helpful?