Update a Vessel

Updates an existing vessel location. The location id and TradePartner.Id identify the records being updated and must remain unchanged.

curl -X PUT "https://connect.wholechain.com/Integration/Location" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Locations": [
    {
      "id": "VESSEL-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Vessel One",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "CaptainsName": "Captain John",
        "Duns": "123456789",
        "Vessel": {
          "VesselName": "Vessel One",
          "VesselFlagState": "United States",
          "IMONumber": "IMO1234567",
          "VesselSatelliteTrackingAuthority": "Tracking Authority",
          "VesselPublicRegistryLink": "https://example.com/vessel/VESSEL-001",
          "VesselRegistration": "REG123456",
          "UnloadingPort": "Port Name"
        },
        "ContactInformation": {
          "Name": "Contact Name",
          "Phone": "+1234567890",
          "Email": "contact@example.com"
        },
        "Address": {
          "City": "Home Port City",
          "State": "Home Port State",
          "Country": "United States",
          "AddressLine1": "123 Harbor Road",
          "AddressLine2": "Dock 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Harbor Road, Home Port City, United States"
        }
      }
    }
  ]
}'

import requests
import json

url = "https://connect.wholechain.com/Integration/Location"
headers = {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string"
}
data = {
  "Locations": [
    {
      "id": "VESSEL-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Vessel One",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "CaptainsName": "Captain John",
        "Duns": "123456789",
        "Vessel": {
          "VesselName": "Vessel One",
          "VesselFlagState": "United States",
          "IMONumber": "IMO1234567",
          "VesselSatelliteTrackingAuthority": "Tracking Authority",
          "VesselPublicRegistryLink": "https://example.com/vessel/VESSEL-001",
          "VesselRegistration": "REG123456",
          "UnloadingPort": "Port Name"
        },
        "ContactInformation": {
          "Name": "Contact Name",
          "Phone": "+1234567890",
          "Email": "contact@example.com"
        },
        "Address": {
          "City": "Home Port City",
          "State": "Home Port State",
          "Country": "United States",
          "AddressLine1": "123 Harbor Road",
          "AddressLine2": "Dock 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Harbor Road, Home Port City, United States"
        }
      }
    }
  ]
}

response = requests.put(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://connect.wholechain.com/Integration/Location", {
  method: "PUT",
  headers: {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string"
},
  body: JSON.stringify({
  "Locations": [
    {
      "id": "VESSEL-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Vessel One",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "CaptainsName": "Captain John",
        "Duns": "123456789",
        "Vessel": {
          "VesselName": "Vessel One",
          "VesselFlagState": "United States",
          "IMONumber": "IMO1234567",
          "VesselSatelliteTrackingAuthority": "Tracking Authority",
          "VesselPublicRegistryLink": "https://example.com/vessel/VESSEL-001",
          "VesselRegistration": "REG123456",
          "UnloadingPort": "Port Name"
        },
        "ContactInformation": {
          "Name": "Contact Name",
          "Phone": "+1234567890",
          "Email": "contact@example.com"
        },
        "Address": {
          "City": "Home Port City",
          "State": "Home Port State",
          "Country": "United States",
          "AddressLine1": "123 Harbor Road",
          "AddressLine2": "Dock 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Harbor Road, Home Port City, United States"
        }
      }
    }
  ]
})
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    data := []byte(`{
  "Locations": [
    {
      "id": "VESSEL-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Vessel One",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "CaptainsName": "Captain John",
        "Duns": "123456789",
        "Vessel": {
          "VesselName": "Vessel One",
          "VesselFlagState": "United States",
          "IMONumber": "IMO1234567",
          "VesselSatelliteTrackingAuthority": "Tracking Authority",
          "VesselPublicRegistryLink": "https://example.com/vessel/VESSEL-001",
          "VesselRegistration": "REG123456",
          "UnloadingPort": "Port Name"
        },
        "ContactInformation": {
          "Name": "Contact Name",
          "Phone": "+1234567890",
          "Email": "contact@example.com"
        },
        "Address": {
          "City": "Home Port City",
          "State": "Home Port State",
          "Country": "United States",
          "AddressLine1": "123 Harbor Road",
          "AddressLine2": "Dock 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Harbor Road, Home Port City, United States"
        }
      }
    }
  ]
}`)

    req, err := http.NewRequest("PUT", "https://connect.wholechain.com/Integration/Location", bytes.NewBuffer(data))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-KEY", "example_string")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://connect.wholechain.com/Integration/Location')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Put.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-KEY'] = 'example_string'
request.body = '{
  "Locations": [
    {
      "id": "VESSEL-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Vessel One",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "CaptainsName": "Captain John",
        "Duns": "123456789",
        "Vessel": {
          "VesselName": "Vessel One",
          "VesselFlagState": "United States",
          "IMONumber": "IMO1234567",
          "VesselSatelliteTrackingAuthority": "Tracking Authority",
          "VesselPublicRegistryLink": "https://example.com/vessel/VESSEL-001",
          "VesselRegistration": "REG123456",
          "UnloadingPort": "Port Name"
        },
        "ContactInformation": {
          "Name": "Contact Name",
          "Phone": "+1234567890",
          "Email": "contact@example.com"
        },
        "Address": {
          "City": "Home Port City",
          "State": "Home Port State",
          "Country": "United States",
          "AddressLine1": "123 Harbor Road",
          "AddressLine2": "Dock 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Harbor Road, Home Port City, United States"
        }
      }
    }
  ]
}'

response = http.request(request)
puts response.body

{}

PUT

/Integration/Location

PUT

Base URLstring

Target server for requests. Edit to use your own host.

Content-Typestring

Required

The media type of the request body

Options: application/json

header

X-API-KEYstring

Required

API key used to authenticate the request.

Locationsarray

Required

Required.

Request Preview

Response

Response will appear here after sending the request

Responses

Success. The live API documentation does not publish a response-body contract for this operation.

Introduction

This API allows you to update an existing vessel in Wholechain.

Because a vessel is stored as a location in Wholechain, the existing vessel is identified using its:

Location id
TradePartner.Id

These IDs identify the existing records and should remain unchanged when submitting an update.

You can update information such as:

Vessel name
Captain's name
Flag state
IMO number
Vessel registration
Satellite tracking authority
Public registry link
Unloading port
Contact information
Home port information
Trade partner name or connection type

The vessel-specific information is stored within the Vessel object. The current location structure supports CaptainsName separately as part of the main Details object.

How It Works

To update a vessel:

Use the existing vessel location id.
Use the existing TradePartner.Id.
Include the updated vessel and location information.
Submit the request using the update endpoint.

For example, if the existing vessel is:

TradePartner.Id: OCEANIC-EXPORTS
Location id: VESSEL-001
Vessel Name: Vessel One
Captain: Captain John

and the captain changes, the IDs remain the same:

TradePartner.Id: OCEANIC-EXPORTS
Location id: VESSEL-001
Vessel Name: Vessel One
Captain: Captain Sarah

You are updating the existing vessel, not creating a new vessel.

Important: Do Not Change the IDs

Location ID

The vessel location id identifies the existing vessel location.

When updating a vessel, use the same id that was originally used to create it.

Existing:
id: VESSEL-001

Update:
id: VESSEL-001

Do not provide a new Location ID when attempting to update an existing vessel.

Trade Partner ID

TradePartner.Id identifies the organization associated with the vessel.

When updating the vessel, use the existing TradePartner.Id.

Existing:
TradePartner.Id: OCEANIC-EXPORTS

Update:
TradePartner.Id: OCEANIC-EXPORTS

The trade partner name or relationship information may be updated, but the ID identifying that trade partner remains the same.

Request Headers

Header	Description	Example Value
`X-API-KEY`	Your Wholechain API key.	`<YOUR_API_KEY>`
`Content-Type`	Content type of the request.	`application/json`
`accept`	Response content type.	`/`

Payload Structure

The request contains a Locations array.

Each vessel contains:

Existing Location ID
Existing Trade Partner ID
Trade partner information
Vessel location information
Captain's name
Vessel information
Contact information
Home port information

The vessel uses the same underlying location structure as when it was created, including the standard location information and additional Vessel object.

Location Object

Column Name	Data Type	Description	Required
`id`	STRING	Existing unique identifier of the vessel location. Use the same ID as the existing vessel.	Yes
`Details`	OBJECT	Contains the trade partner, location, and vessel information.	Yes

Details Object

Column Name	Data Type	Description
`TradePartner`	OBJECT	Identifies the existing trade partner associated with the vessel.
`Name`	STRING	Name of the vessel location.
`Gln`	STRING	Global Location Number associated with the location, if applicable.
`Extension`	STRING	Additional identifier or extension associated with the location.
`CaptainsName`	STRING	Name of the vessel captain.
`Duns`	STRING	DUNS number associated with the location.
`Vessel`	OBJECT	Contains vessel-specific information.
`ContactInformation`	OBJECT	Contact information associated with the vessel.
`Address`	OBJECT	Home port information associated with the vessel.

Trade Partner Object

The TradePartner object identifies the organization associated with the vessel.

Column Name	Data Type	Description
`Id`	STRING	Existing Trade Partner ID. Keep this value unchanged when updating the existing trade partner.
`Name`	STRING	Name of the trade partner.
`ConnectionType`	STRING	Relationship between the trade partner and your Wholechain account.

Connection Type

Supported connection types are:

Connection Type	Description
`SELF`	The trade partner represents your own organization.
`SUPPLIER`	The trade partner supplies products or materials to your organization.
`BUYER`	The trade partner purchases products or materials from your organization.

The connection type describes the relationship between your Wholechain account and the trade partner, not the function of the vessel itself.

Vessel Object

The Vessel object contains the vessel-specific information that can be updated.

Column Name	Data Type	Description
`VesselName`	STRING	Name of the vessel.
`VesselFlagState`	STRING	Country or state under which the vessel is registered or flagged.
`IMONumber`	STRING	International Maritime Organization number associated with the vessel, if applicable.
`VesselSatelliteTrackingAuthority`	STRING	Authority or system responsible for the vessel's satellite tracking.
`VesselPublicRegistryLink`	STRING	Public URL where vessel registration information can be verified.
`VesselRegistration`	STRING	Vessel registration number or identifier.
`UnloadingPort`	STRING	Port where the vessel unloads its catch or product.

These are the vessel-specific fields currently contained within the Wholechain Vessel object.

Contact Information Object

The contact information associated with the vessel can also be updated.

Column Name	Data Type	Description
`Name`	STRING	Name of the primary contact for the vessel.
`Phone`	STRING	Contact phone number.
`Email`	STRING	Contact email address.

Address Object

The Address object represents the home port associated with the vessel.

When updating the address information, provide the updated information for the vessel's home port.

This does not represent the vessel's current or live geographic position.

For example, if a vessel changes its registered home port from one port to another, the Address object can be updated to reflect the new home port.

Column Name	Data Type	Description
`City`	STRING	City of the vessel's home port.
`State`	STRING	State, province, or region of the home port.
`Country`	STRING	Country of the vessel's home port.
`AddressLine1`	STRING	Primary address line for the home port.
`AddressLine2`	STRING	Secondary address line, if applicable.
`PostalCode`	STRING	Postal or ZIP code of the home port.
`GeoCoordinates`	OBJECT	Latitude and longitude of the home port.
`DisplayAddress`	STRING	Formatted human-readable address of the home port.

GeoCoordinates Object

Column Name	Data Type	Description
`Latitude`	DECIMAL	Latitude of the vessel's home port.
`Longitude`	DECIMAL	Longitude of the vessel's home port.

The coordinates should identify the vessel's home port, not its position while at sea.

Example: Update Vessel Information

Assume VESSEL-001 already exists in Wholechain and belongs to OCEANIC-EXPORTS.

The following request updates information about that vessel while retaining the same Location ID and Trade Partner ID.

{
  "Locations": [
    {
      "id": "VESSEL-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Vessel One",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "CaptainsName": "Captain Sarah",
        "Duns": "123456789",
        "Vessel": {
          "VesselName": "Vessel One",
          "VesselFlagState": "United States",
          "IMONumber": "IMO1234567",
          "VesselSatelliteTrackingAuthority": "Updated Tracking Authority",
          "VesselPublicRegistryLink": "https://example.com/vessel/VESSEL-001",
          "VesselRegistration": "REG123456",
          "UnloadingPort": "Updated Port Name"
        },
        "ContactInformation": {
          "Name": "Contact Name",
          "Phone": "+1234567890",
          "Email": "contact@example.com"
        },
        "Address": {
          "City": "Home Port City",
          "State": "Home Port State",
          "Country": "United States",
          "AddressLine1": "123 Harbor Road",
          "AddressLine2": "Dock 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Harbor Road, Home Port City, United States"
        }
      }
    }
  ]
}

In this example:

UNCHANGED
TradePartner.Id: OCEANIC-EXPORTS
Location id: VESSEL-001

UPDATED
Captain: Captain Sarah
Satellite Tracking Authority: Updated Tracking Authority
Unloading Port: Updated Port Name

The existing IDs allow Wholechain to identify which vessel and trade partner should be updated.

Example: Update the Vessel's Home Port

If the vessel's home port changes, keep the vessel and trade partner IDs the same and update the Address object.

{
  "Locations": [
    {
      "id": "VESSEL-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Vessel One",
        "Address": {
          "City": "New Home Port City",
          "State": "New Home Port State",
          "Country": "United States",
          "AddressLine1": "456 Harbor Road",
          "PostalCode": "54321",
          "GeoCoordinates": {
            "Latitude": 21.345678,
            "Longitude": 88.765432
          },
          "DisplayAddress": "456 Harbor Road, New Home Port City, United States"
        }
      }
    }
  ]
}

The Address update changes the vessel's home port information. It is not used to record movements or the vessel's current location.

What Can Be Updated?

You can update information associated with the vessel while continuing to use the existing vessel and trade partner IDs.

For example:

VESSEL-001
│
├── Vessel Name
├── Captain
├── Flag State
├── IMO Number
├── Vessel Registration
├── Satellite Tracking Authority
├── Public Registry Link
├── Unloading Port
├── Contact Information
└── Home Port Information

Important Notes

A vessel is stored as a location in Wholechain.
Use the existing vessel location id when updating a vessel.
Use the existing TradePartner.Id when updating the trade partner associated with the vessel.
Do not change the Location ID when attempting to update an existing vessel.
Do not change the Trade Partner ID when attempting to update the existing trade partner.
CaptainsName is stored in the main Details object.
Vessel-specific information is stored within the Vessel object.
The Address object represents the vessel's home port.
Address coordinates represent the home port and not the vessel's live geographic position.
Vessel information such as the captain, flag state, IMO number, registration, tracking authority, registry link, and unloading port can be updated.
Contact information associated with the vessel can be updated.
Trade partner details such as the name or ConnectionType can be updated while retaining the existing TradePartner.Id.
You can only update vessel/location records that belong to your account. Locations shared with your account by another trade partner are not editable through this update.
If you need to register a different vessel rather than modify the existing vessel, create a new vessel with its own unique Location ID instead.

Was this page helpful?