Create Trade Partners & Locations

Creates one or more standard locations together with their associated trade-partner information. Vessel-specific properties are documented in the separate Vessel API specification.

curl -X POST "https://connect.wholechain.com/Integration/Locations" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Locations": [
    {
      "id": "OCEANIC-PLANT-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Oceanic Processing Plant",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "Duns": "123456789",
        "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": "Building 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Main St, City Name, State Name, Country Name, 12345"
        }
      }
    }
  ]
}'

import requests
import json

url = "https://connect.wholechain.com/Integration/Locations"
headers = {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string"
}
data = {
  "Locations": [
    {
      "id": "OCEANIC-PLANT-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Oceanic Processing Plant",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "Duns": "123456789",
        "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": "Building 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Main St, City Name, State Name, Country Name, 12345"
        }
      }
    }
  ]
}

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": "OCEANIC-PLANT-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Oceanic Processing Plant",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "Duns": "123456789",
        "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": "Building 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Main St, City Name, State Name, Country Name, 12345"
        }
      }
    }
  ]
})
});

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

package main

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

func main() {
    data := []byte(`{
  "Locations": [
    {
      "id": "OCEANIC-PLANT-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Oceanic Processing Plant",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "Duns": "123456789",
        "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": "Building 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Main St, City Name, State Name, Country Name, 12345"
        }
      }
    }
  ]
}`)

    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": "OCEANIC-PLANT-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Oceanic Processing Plant",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "Duns": "123456789",
        "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": "Building 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Main St, City Name, State Name, Country Name, 12345"
        }
      }
    }
  ]
}'

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 trade partner together with one or more associated locations in Wholechain.

A trade partner represents the organization associated with a location. It may represent:

Your own organization
A supplier
A buyer or customer

A location represents a physical place associated with that organization, such as a:

Processing plant
Warehouse
Distribution center
Office
Port
Farm
Supplier facility
Customer facility

When creating a location, the TradePartner object defines both the organization the location belongs to and the relationship between that organization and your Wholechain account.

If the TradePartner.Id does not already exist, the trade partner can be created as part of the same request.

If the trade partner already exists, reuse its existing TradePartner.Id when creating additional locations for that organization.

Vessel locations use the same endpoint but contain additional vessel-specific information. See the separate Create a Vessel documentation.

How It Works

Each entry in the Locations array contains:

A unique Location ID
A TradePartner object
A ConnectionType
Location details
Contact information
Address or geographic information

The trade partner and location can therefore be created together in one request.

For example, in the following relationship:

Oceanic Exports
└── Oceanic Processing Plant

Important: Unique IDs

Both trade partners and locations require unique identifiers.

Trade Partner ID

TradePartner.Id uniquely identifies the organization.

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

If several locations belong to the same organization, reuse the same TradePartner.Id.

Location ID

Every location must have its own unique id.

Do not reuse an existing Location ID for a different physical location.

For example:

TradePartner.Id: OCEANIC-EXPORTS

Location 1:
id: OCEANIC-PLANT-001

Location 2:
id: OCEANIC-PLANT-002

Both locations belong to OCEANIC-EXPORTS, but each physical location has its own 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 locations can be created in a single request.

Each location contains:

A unique location ID
Trade partner information
Connection type
Location information
Contact information
Address or geographic information

Location Object

Column Name	Data Type	Description	Required
`id`	STRING	Unique identifier for the location. This ID must not be reused for a different location.	Yes
`Details`	OBJECT	Contains the trade partner and detailed location information.	Yes

Details Object

Column Name	Data Type	Description	Required
`TradePartner`	OBJECT	Creates or identifies the trade partner associated with this location and defines its relationship to your account.	Yes
`Name`	STRING	Name of the 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
`Duns`	STRING	DUNS number associated with the location. Must contain 9 or 13 digits.	No
`ContactInformation`	OBJECT	Contact information associated with the location.	No
`Address`	OBJECT	Physical address or geographic information for the location.	Yes

Trade Partner Object

The TradePartner object represents the organization associated with the location.

It can be used to:

Create a new trade partner together with a location.
Associate a new location with an existing trade partner.

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

If multiple locations belong to the same trade partner, use the same TradePartner.Id and TradePartner.Name for each location.

For example:

{
  "TradePartner": {
    "Id": "OCEANIC-EXPORTS",
    "Name": "Oceanic Exports",
    "ConnectionType": "SUPPLIER"
  }
}

Connection Type

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

Supported values 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.
OTHER	The trade partner purchases an sells products or materials from/to your organization.

The connection type describes your business relationship with the trade partner, not the physical function of the location.

SELF

Use SELF when creating a trade partner representing your own organization or when creating locations belonging to your own organization.

{
  "TradePartner": {
    "Id": "MY-COMPANY",
    "Name": "My Company",
    "ConnectionType": "SELF"
  }
}

You can then create multiple locations under the same trade partner:

MY-COMPANY
├── Amsterdam Warehouse
├── Rotterdam Distribution Center
└── Head Office

Each location has a different Location ID but uses the same TradePartner.Id.

SUPPLIER

Use SUPPLIER when the organization supplies products or materials to your business.

{
  "TradePartner": {
    "Id": "SUPPLIER-001",
    "Name": "Oceanic Exports",
    "ConnectionType": "SUPPLIER"
  }
}

BUYER

Use BUYER when the organization purchases products or materials from your business.

{
  "TradePartner": {
    "Id": "BUYER-001",
    "Name": "Seafood Retailer",
    "ConnectionType": "BUYER"
  }
}

Contact Information Object

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

Address Object

Column Name	Data Type	Description	Required
`City`	STRING	City of the location.	Yes
`State`	STRING	State, province, or region 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 or ZIP code.	No
`GeoCoordinates`	OBJECT	Latitude and longitude of the location.	Yes, if address details are not provided
`DisplayAddress`	STRING	Formatted human-readable address.	No

GeoCoordinates Object

Column Name	Data Type	Description
`Latitude`	DECIMAL	Latitude of the location.
`Longitude`	DECIMAL	Longitude of the location.

If a standard street address is unavailable, geographic coordinates can be used to identify the location.

Example: Create a Trade Partner and Location

The following example creates the trade partner Oceanic Exports together with one processing location.

{
  "Locations": [
    {
      "id": "OCEANIC-PLANT-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER"
        },
        "Name": "Oceanic Processing Plant",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "Duns": "123456789",
        "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": "Building 4",
          "PostalCode": "12345",
          "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
          },
          "DisplayAddress": "123 Main St, City Name, State Name, Country Name, 12345"
        }
      }
    }
  ]
}

This creates:

Trade Partner
Oceanic Exports
Id: OCEANIC-EXPORTS
ConnectionType: SUPPLIER
        │
        └── Location
            Oceanic Processing Plant
            Id: OCEANIC-PLANT-001

Example: Create Multiple Locations for the Same Trade Partner

If one trade partner has multiple physical locations, reuse the same trade partner information for each location.

{
  "Locations": [
    {
      "Id": "OCEANIC-PLANT-001",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER",
          "Duns": "123456789"
        },
        "Name": "Oceanic Processing Plant 1",
        "Gln": "9506000140445",
        "Extension": "Plant1",
        "DunsPlus4": "0001",
        "ContactInformation": {
          "Name": "Plant 1 Contact",
          "Phone": "+1234567890",
          "Email": "plant1@oceanicexports.com"
        },
        "Address": {
          "City": "Cape Town",
          "State": "Western Cape",
          "Country": "South Africa",
          "AddressLine1": "123 Processing Street",
          "AddressLine2": "Building 1",
          "PostalCode": "8001"
        }
      }
    },
    {
      "Id": "OCEANIC-PLANT-002",
      "Details": {
        "TradePartner": {
          "Id": "OCEANIC-EXPORTS",
          "Name": "Oceanic Exports",
          "ConnectionType": "SUPPLIER",
          "Duns": "123456789"
        },
        "Name": "Oceanic Processing Plant 2",
        "Gln": "9506000140446",
        "Extension": "Plant2",
        "DunsPlus4": "0002",
        "ContactInformation": {
          "Name": "Plant 2 Contact",
          "Phone": "+1234567891",
          "Email": "plant2@oceanicexports.com"
        },
        "Address": {
          "City": "Cape Town",
          "State": "Western Cape",
          "Country": "South Africa",
          "AddressLine1": "456 Processing Street",
          "AddressLine2": "Building 2",
          "PostalCode": "8002"
        }
      }
    }
  ]
}

This creates the following structure:

Oceanic Exports
TradePartner.Id: OCEANIC-EXPORTS
│
├── Oceanic Processing Plant 1
│   id: OCEANIC-PLANT-001
│
└── Oceanic Processing Plant 2
    id: OCEANIC-PLANT-002

OCEANIC-EXPORTS is reused because both locations belong to the same organization.

Each location has a different id because every physical location must have its own unique identifier.

Vessel-specific fields are not covered on this page. See Create a Vessel for vessel locations.

Important Notes

This API can create a trade partner and its associated location together.
Every trade partner must have a unique TradePartner.Id.
Do not reuse a TradePartner.Id for a different organization.
Every location must have a unique id.
Do not reuse a Location ID for a different physical location.
If multiple locations belong to the same organization, reuse the same TradePartner.Id.
Each individual location must still have its own unique Location ID.
ConnectionType must describe the relationship between the trade partner and your Wholechain account.
Use SELF for your own organization.
Use SUPPLIER for organizations that supply your business.
Use BUYER for organizations that purchase from your business.
If the trade partner already exists, reuse its existing TradePartner.Id when adding another location.
If a physical address is unavailable, GeoCoordinates can be used to identify the location.

Was this page helpful?