Sites: Pickup / Delivery Location

Pickup and delivery locations are referred to as sites in X4Fleet. New sites are automatically imported and created during POST Shipment. If orders are entered manually or if the site catalogue is to be synchronised between the upstream system and X4Fleet, the following API endpoints can be used.

Endpoints

POST /x4gateway/v1/import/poi

as well as
GET /x4gateway/v1/import/poi/{id} --> normal GET request by site ID
GET /x4gateway/v1/import/poi --> GET request by RefID
GET /x4gateway/v1/import/pois --> site search by various parameters with pagination function
DELETE /x4gateway/v1/import/poi/{id} --> normal DELETE request by site ID

With DELETE, only sites of your own main group can be deleted. If the site belongs to another main group, it is not deleted and the API responds with HTTP 400 and error code 2. When a site is deleted, its links to business partners and to WebOrder orderers as well as the site's stock levels are removed. The site itself is deactivated (not permanently deleted).

With POST site and when importing orders, too, only site IDs of your own main group can be used. If the ID of a site belonging to another main group is sent, the import fails with the message "Location with Id=… was not found."

Request

{
	"clients": [
		{
			"refId": "string"					//sites can belong to business partners; these can be linked here via the business partner RefID
		}
	],
	"kind": 0,								//site kind
	"name": "string",
	"askForSignature": true,
	"name2": "string",
	"organization": "string",
	"contactPhone": "string",
	"contactPhone1": "string",
	"contactPhone2": "string",
	"fax": "string",
	"driverImages": "string",					//site photos for the drivers
	"driverTextInformation": "string",			//site information for the drivers
	"serviceProvisionNumber": "string",
	"openPickupTpOnlyOverBarCode": true,
	"openDropoffTpOnlyOverBarCode": true,
	"openPickupTpOnlyWhenNear": true,
	"openDropoffTpOnlyWhenNear": true,
	"nearToPickupTpDistance": 0,
	"nearToDropoffTpDistance": 0,
	"active": true,
	"allowUpdateOverGateway": true,			//default true; only applied when the site is created
	"validFrom": "2026-02-26T14:59:08.057Z",
	"validUntil": "2026-02-26T14:59:08.057Z",
	"stopTimeMinutes": 0,
	"email": "string",
	"contacts": [{}],							//site contacts, structure and rules as for business partners
	"attachments": [{}],						//attachments visible to both dispatcher and driver
	"specialities": [{}],						//specialities (e.g. only accessible via loading ramp)
	"loadingTools": [{}],						//loading tools
    "location": {
        "name": "string",            //obsolete/deprecated
        "streetAddress": "string",
        "postCode": "string",
        "city": "string",
        "countryCode": "string",     //2-letter country code, e.g. CH, DE, FR
        "coordinates": {             //if no address exists or it is not precise enough
            "lat": 47.193913,        //if no coordinates are sent, the address is automatically geocoded
            "lng": 8.5235162
        },
    },
	"advisingConfig": {},
	"poiDocument": {},
	"notes": "string",
	"dispatcherNotes": "string",		    	//notes that are not visible to the drivers
	"refId": "string",						//important: if no RefID is set, the site is interpreted as a new site and a RefID is generated automatically
}

Used enums: Site kind.

If an ID or RefID is provided in the POST request and a site with this ID or RefID already exists, it will be overwritten.

allowUpdateOverGateway determines whether a site may later be updated via the API. The value is true by default and is only applied when the site is newly created; for an existing site, a value sent in the request has no effect. If the value is false, later imports no longer change the site: fields, address, contacts, specialities and loading tools remain unchanged. The field is also available for sites sent in an order as pickup or delivery location (shipmentLocation).

The same fields and update rules apply to site contacts (contacts) as to the contacts of business partners.

Response

The response structure is analogous to the request structure; all information sent in the POST as well as system-added information is returned.

The ID / site ID is important information that should ideally be stored in the upstream system.

Common Error Messages

GET:

• {"code":5,"messages":["Pickup / Dropoff with this id or refNr does not exist"],"RequestId":null,"Id":0}

DELETE:

• {"code":2,"messages":["X4FleetGroupId is wrong for this Pickup / Dropoff."],"RequestId":null,"Id":0}
  --> The site does not belong to your own main group and cannot be deleted.
• {"code":5,"messages":["Pickup / Dropoff with this id or refNr does not exist"],"RequestId":null,"Id":0}
  --> No site with this ID exists.

POST:

• {"code":99,"messages":["There was an general error","Location with Id=XXX was not found."],"RequestId":null,"Id":0}
  --> The site ID sent belongs to another main group.