Create a Vessel

Creates one or more vessel locations together with their associated trade-partner, contact, and home-port information.

curl -X POST "https://connect.wholechain.com/Integration/Locations" \
  -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/Locations"
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.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://connect.wholechain.com/Integration/Locations", {
  method: "POST",
  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("POST", "https://connect.wholechain.com/Integration/Locations", 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/Locations')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.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

{
  "message": "Success",
  "result": [
    {
      "id": "01a0d84d-7aba-76bd-97b7-c2309d6f9bd4",
      "status": "Created"
    }
  ],
  "errors": [],
  "validations": []
}

POST

/Integration/Locations

POST

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

messagestring

Required

resultarray

Required

errorsobject[]

Required

validationsobject[]

Required

Introduction

This API allows you to create a vessel location in Wholechain.

A vessel is treated as a location within Wholechain, meaning it must still include the standard location and trade partner information.

In addition, vessel locations can include vessel-specific traceability information such as:

Vessel name
Captain's name
Flag state
IMO number
Vessel registration
Satellite tracking authority
Public registry link
Unloading port

The vessel can be created together with the trade partner it belongs to.

If the trade partner already exists, reuse the existing TradePartner.Id.

How It Works

A vessel request contains:

A unique Location ID
Trade partner information
Connection type
Standard location information
Vessel-specific information
Contact information
Home port address information

The Address object represents the home port associated with the vessel. It should not be used to represent the vessel's current or live position.

For example:

Oceanic Exports
└── Vessel One
    └── Home Port: Port of Example

The trade partner represents the organization operating or associated with the vessel, while the vessel itself is registered as a location.

Important: Unique IDs

Trade Partner ID

TradePartner.Id uniquely identifies the organization associated with the vessel.

Do not reuse the same TradePartner.Id for a different organization.

If multiple vessels or other locations belong to the same trade partner, reuse the same TradePartner.Id.

Location ID

Every vessel must have its own unique location id.

For example:

TradePartner.Id: OCEANIC-EXPORTS

Vessel 1:
id: VESSEL-001

Vessel 2:
id: VESSEL-002

Both vessels may belong to the same trade partner, but each vessel must have its own unique location ID.

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.

Multiple vessels can be created in a single request.

Each vessel contains:

A unique location ID
Trade partner information
Connection type
Location information
Captain's name
Vessel information
Contact information
Home port address information

Location Object

Column Name	Data Type	Description	Required
`id`	STRING	Unique identifier for the vessel location.	Yes
`Details`	OBJECT	Contains the trade partner, location, and vessel information.	Yes

Details Object

Column Name	Data Type	Description	Required
`TradePartner`	OBJECT	Creates or identifies the trade partner associated with the vessel.	Yes
`Name`	STRING	Name of the vessel location.	Yes
`Gln`	STRING	Global Location Number associated with the location, if applicable.	No
`Extension`	STRING	Additional identifier or extension associated with the location.	No
`CaptainsName`	STRING	Name of the vessel captain.	No
`Duns`	STRING	DUNS number associated with the location. Must contain 9 or 13 digits.	No
`Vessel`	OBJECT	Contains vessel-specific traceability information.	Yes for vessel locations
`ContactInformation`	OBJECT	Contact information associated with the vessel.	Yes
`Address`	OBJECT	Address information for the vessel's home port.	Yes

Trade Partner Object

The TradePartner object identifies the organization associated with the vessel.

It can be used to:

Create a new trade partner together with the vessel.
Associate a vessel with an existing trade partner.

Column Name	Data Type	Description	Required
`Id`	STRING	Unique identifier for the trade partner. Reuse the existing ID if the trade partner already exists.	Yes
`Name`	STRING	Name of the trade partner.	Yes
`ConnectionType`	STRING	Defines the relationship between the trade partner and your Wholechain account.	Yes

Connection Type

ConnectionType defines the relationship between your Wholechain account and the trade partner associated with the vessel.

Supported values are:

Connection Type	Description
`SELF`	The vessel belongs to your own organization.
`SUPPLIER`	The vessel belongs to an organization that supplies products or materials to you.
`BUYER`	The vessel belongs to an organization that purchases products or materials from you.

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 additional information used to identify and describe the vessel.

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

Contact Information Object

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

Address Object

The Address object represents the home port of the vessel.

This is the port or location the vessel is primarily associated with or based from. It does not represent the vessel's current location while at sea.

Where available, provide the physical address of the vessel's home port. If a standard street address is not available, geographic coordinates can be used to identify the home port.

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

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.

These coordinates should identify the vessel's home port, not its real-time position or location at the time of an event.

Example Request

The following example creates a vessel called Vessel One associated with the supplier Oceanic Exports.

{
  "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"
        }
      }
    }
  ]
}

In this example, the Address information represents the home port associated with Vessel One. It does not represent the vessel's current geographic position.

Important Notes

A vessel is treated as a location in Wholechain.
Vessel locations use the /Integration/Locations endpoint.
Include the Vessel object when creating a vessel.
CaptainsName is stored in the main Details object.
VesselName is stored within the Vessel object.
The Address object represents the vessel's home port.
Address coordinates should identify the home port, not the vessel's live position.
Every vessel must have a unique location id.
If multiple vessels belong to the same organization, reuse the same TradePartner.Id.
If the trade partner does not already exist, it can be created as part of the same request.
If the trade partner already exists, reuse its existing TradePartner.Id.
Use SELF, SUPPLIER, or BUYER to define the trade partner's relationship to your Wholechain account.

Was this page helpful?