Adding Locations/Trade Partners

Endpoint URL

https://connect.wholechain.com/Integration/Locations

Sandbox URL

https://connect-sandbox.wholechain.com/Integration/Locations

Method

POST

Create or Update Trade Partners and Locations

This API allows you to create a new trade partner along with multiple locations or update an existing trade partner by adding new locations. If you are creating a new trade partner, include the trade partner information along with the location details. If you are updating an existing trade partner, use the trade partner's existing details and only include the new location(s).

Introduction

Create a New Trade Partner: Provide trade partner details along with one or more associated locations.
Update an Existing Trade Partner: Use the trade partner's existing details to add new locations.
This flexibility ensures that you can manage your trade partners and their locations seamlessly within the Wholechain system.

Practical Examples

New Trade Partner: Create a new trade partner called "Oceanic Exports" and assign two associated locations for their offices or vessels.
Update Trade Partner: Add a new unloading port location for the trade partner "Oceanic Exports" using their existing trade partner ID.

Authentication

The API uses an API key (X-API-KEY) to authenticate requests. Each user has a unique API key that controls access to the trade partner and location management. For more information, refer to the Authentication page.

Request Headers

Header	Description	Example Value
`X-API-KEY`	Your API key	`733e286e-c578-461d-afc6-bd82efe4e6bb`
`Content-Type`	Content type of the request	`application/json`
`accept`	Response content type	`/`

Payload Structure

Location Object

Column Name	Data Type	Description	Required
`id`	STRING	Unique identifier for the location.	Yes
`Details`	OBJECT	Contains detailed information about the location.	Yes

Details Object

Column Name	Data Type	Description	Required
`TradePartner`	OBJECT	Trade partner details for this location.	Yes
`Name`	STRING	Name of the location.	Yes
`Gln`	STRING	Global Location Number.	No
`Extension`	STRING	Additional details or extension for the location.	No
`CaptainsName`	STRING	Name of the captain, if applicable.	No
`Duns`	STRING	DUNS number of the location. Must be 9 or 13 digits	No
`Vessel`	OBJECT	Vessel details, if applicable. Leave Object blank if not needed	No
`ContactInformation`	OBJECT	Contact details for the location.	Yes
`Address`	OBJECT	Address information for the location.	Yes

TradePartner Object

Column Name	Data Type	Description	Required
`Id`	STRING	Unique identifier for the trade partner.	Yes
`Name`	STRING	Name of the trade partner.	Yes
`ConnectionType`	STRING	Type of connection (e.g., `BUYER`, `SUPPLIER`).	Yes

Address Object

Column Name	Data Type	Description	Required
`City`	STRING	City of the location.	Yes
`State`	STRING	State of the location.	No
`Country`	STRING	Country of the location.	Yes
`AddressLine1`	STRING	Primary address line.	Yes
`AddressLine2`	STRING	Secondary address line, if applicable.	No
`PostalCode`	STRING	Postal code of the location.	Yes
`GeoCoordinates`	OBJECT	Latitude and longitude of the location.	Yes
`DisplayAddress`	STRING	Formatted display address.	Yes

Example Requests

PythonC#Curl

import requests

url = 'https://connect.wholechain.com/Integration/TradePartners'
headers = {
    'accept': '*/*',
    'X-API-KEY': '733e286e-c578-461d-afc6-bd82efe4e6bb',
    'Content-Type': 'application/json'
}
data = {
    "Locations": [
        {
            "id": "MyId123",
            "Details": {
                "TradePartner": {
                    "Id": "TpId123",
                    "Name": "Trade Partner Name",
                    "ConnectionType": "BUYER"
                },
                "Name": "MyLocation",
                "Gln": "9506000140445",
                "Extension": "SomeExtension",
                "CaptainsName": "Captain John",
                "Duns": "1234",
                "Vessel": {
                    "VesselName": "Vessel One",
                    "VesselFlagState": "Flag State",
                    "IMONumber": "IMO1234567",
                    "VesselSatelliteTrackingAuthority": "Authority",
                    "VesselPublicRegistryLink": "http://registry.link",
                    "VesselRegistration": "Registration123",
                    "UnloadingPort": "Port Name"
                },
                "ContactInformation": {
                    "Name": "Contact Name",
                    "Phone": "+1234567890",
                    "Email": "contact@example.com"
                },
                "Address": {
                    "City": "City Name",
                    "State": "State Name",
                    "Country": "Country Name",
                    "AddressLine1": "123 Main St",
                    "AddressLine2": "Apt 4B",
                    "PostalCode": "12345",
                    "GeoCoordinates": {
                        "Latitude": 12.345678,
                        "Longitude": 98.765432
                    },
                    "DisplayAddress": "123 Main St, Apt 4B, City Name, State Name, Country Name, 12345"
                }
            }
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

print(response.status_code)
print(response.json())

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://connect.wholechain.com/Integration/TradePartners";
        var apiKey = "733e286e-c578-461d-afc6-bd82efe4e6bb";

        var data = new
        {
            Locations = new[]
            {
                new
                {
                    id = "MyId123",
                    Details = new
                    {
                        TradePartner = new
                        {
                            Id = "TpId123",
                            Name = "Trade Partner Name",
                            ConnectionType = "BUYER"
                        },
                        Name = "MyLocation",
                        Gln = "9506000140445",
                        Extension = "SomeExtension",
                        CaptainsName = "Captain John",
                        Duns = "1234",
                        Vessel = new
                        {
                            VesselName = "Vessel One",
                            VesselFlagState = "Flag State",
                            IMONumber = "IMO1234567",
                            VesselSatelliteTrackingAuthority = "Authority",
                            VesselPublicRegistryLink = "http://registry.link",
                            VesselRegistration = "Registration123",
                            UnloadingPort = "Port Name"
                        },
                        ContactInformation = new
                        {
                            Name = "Contact Name",
                            Phone = "+1234567890",
                            Email = "contact@example.com"
                        },
                        Address = new
                        {
                            City = "City Name",
                            State = "State Name",
                            Country = "Country Name",
                            AddressLine1 = "123 Main St",
                            AddressLine2 = "Apt 4B",
                            PostalCode = "12345",
                            GeoCoordinates = new
                            {
                                Latitude = 12.345678,
                                Longitude = 98.765432
                            },
                            DisplayAddress = "123 Main St, Apt 4B, City Name, State Name, Country Name, 12345"
                        }
                    }
                }
            }
        };

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("accept", "*/*");
            client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);

            var json = JsonConvert.SerializeObject(data);
            var content = new StringContent(json, Encoding.UTF8, "application/json");

            try
            {
                var response = await client.PostAsync(url, content);

                Console.WriteLine($"Status Code: {response.StatusCode}");
                var responseContent = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseContent);
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
}

curl -X POST https://connect.wholechain.com/Integration/TradePartners \
-H "accept: */*" \
-H "X-API-KEY: 733e286e-c578-461d-afc6-bd82efe4e6bb" \
-H "Content-Type: application/json" \
-d '{
    "Locations": [
        {
            "id": "MyId123",
            "Details": {
                "TradePartner": {
                    "Id": "TpId123",
                    "Name": "Trade Partner Name",
                    "ConnectionType": "BUYER"
                },
                "Name": "MyLocation",
                "Gln": "9506000140445",
                "Extension": "SomeExtension",
                "CaptainsName": "Captain John",
                "Duns": "1234",
                "Vessel": {
                    "VesselName": "Vessel One",
                    "VesselFlagState": "Flag State",
                    "IMONumber": "IMO1234567",
                    "VesselSatelliteTrackingAuthority": "Authority",
                    "VesselPublicRegistryLink": "http://registry.link",
                    "VesselRegistration": "Registration123",
                    "UnloadingPort": "Port Name"
                },
                "ContactInformation": {
                    "Name": "Contact Name",
                    "Phone": "+1234567890",
                    "Email": "contact@example.com"
                },
                "Address": {
                    "City": "City Name",
                    "State": "State Name",
                    "Country": "Country Name",
                    "AddressLine1": "123 Main St",
                    "AddressLine2": "Apt 4B",
                    "PostalCode": "12345",
                    "GeoCoordinates": {
                        "Latitude": 12.345678,
                        "Longitude": 98.765432
                    },
                    "DisplayAddress": "123 Main St, Apt 4B, City Name, State Name, Country Name, 12345"
                }
            }
        }
    ]
}'

Example Payload

JSON

{
    "Locations": [
        {
            "id": "MyId123",
            "Details": {
                "TradePartner": {
                    "Id": "TpId123",
                    "Name": "Trade Partner Name",
                    "ConnectionType": "BUYER"
                },
                "Name": "MyLocation",
                "Gln": "9506000140445",
                "Extension": "SomeExtension",
                "CaptainsName": "Captain John",
                "Duns": "1234",
                "Vessel": {
                    "VesselName": "Vessel One",
                    "VesselFlagState": "Flag State",
                    "IMONumber": "IMO1234567",
                    "VesselSatelliteTrackingAuthority": "Authority",
                    "VesselPublicRegistryLink": "http://registry.link",
                    "VesselRegistration": "Registration123",
                    "UnloadingPort": "Port Name"
                },
                "ContactInformation": {
                    "Name": "Contact Name",
                    "Phone": "+1234567890",
                    "Email": "contact@example.com"
                },
                "Address": {
                    "City": "City Name",
                    "State": "State Name",
                    "Country": "Country Name",
                    "AddressLine1": "123 Main St",
                    "AddressLine2": "Apt 4B",
                    "PostalCode": "12345",
                    "GeoCoordinates": {
                        "Latitude": 12.345678,
                        "Longitude": 98.765432
                    },
                    "DisplayAddress": "123 Main St, Apt 4B, City Name, State Name, Country Name, 12345"
                }
            }
        }
    ]
}