Partner API

Usage

The LoadFox Partner API enables you, as a partner company of LoadFox, to interact with our system in a programmatic way and integrate LoadFox seemlessly into your IT solution. This documentation provides you with a complete and in-depth description of the LoadFox Partner API.

Environments

LoadFox provides two environments, one for testing („Test“), one for production („Production“) with the following endpoints:

Environment Name URL
Test https://demo.loadfox.eu/api/partners/
Production https://app.loadfox.eu/api/partners/

Versioning

To ensure LoadFox can create and publish new versions of their application/endpoints without impacting our partners, the API version is part of the URL for each method. This means, partners can choose which version of a method they would like to use. The version value is increased if a method signature changes in a way that it’s no longer backward/forward compatible. This will happen very rarely.

The versioning scheme is [major].[minor].[maintenance], e.g. 1.2.3. Only the major version is included in the URL, as “maintenance” will not change the API interface at all and “minor” will have only backward/forward compatible changes.

URL example: https://demo.loadfox.eu/api/partners/v1/loads

Security

Authentication

In order to invoke Partner API endpoints an authenticatin token must be provided in the request header. The authentication token must be included as plain text in each request as header “X-Auth-Token”.

Two types of authentication tokens exist:

  • user authentication tokens: Allow to use the Partner API in the context of a specific user. A user authentication token can be obtained from the getUserToken API.
  • company authentication tokens: Allow to use the Partner API in the context of a company. For example, it allows to create a load for any user of the company, and it is possible to create users. A company authentication token can be obtained from the getCompanyToken API (using a company ID/secret provided by LoadFox).

To use the getCompanyToken or getUserToken APIs you need to provide an application ID and secret that you’ll get from LoadFox. Please contact LoadFox support if you would like to use our Partner API.

Encryption

All requests / responses MUST be sent over SSL/TLS. All endpoints support and use TLS 1.2 or TLS 1.1, weak versions (e.g. TLS 1.0, SSL 3) are disabled. Only cipher suites that meet requirements for strong cryptography are enabled.

Content

Checking the content (e.g. receiving user uploaded and forwarded files in requests / responses) for virus infection and other malicious data (e.g. XSS) is up to each partner.

HTTP Status Codes

The LoadFox API uses the following http status codes.

Code Text Description
200 OK Operation processed was successfuly.
400 Bad Request The request was invalid or cannot be otherwise served, so default code for a failed request (e.g. wrong json format / not deserializable, wrong content type)
401 Unauthorized Missing or invalid authentication credentials
403 Forbidden The request is understood, but it has been refused or access is not allowed.
404 Not Found The URI requested is invalid or there is no endpoint with this url
406 Not Acceptable Returned when an invalid format is specified in the request.
410 Gone This endpoint is gone. Used to indicate that an API endpoint has been turned off.
429 Too Many Requests Returned when a request cannot be served due to the application’s rate limit having been exhausted
500 Internal Server Error Something is broken, please contact Loadfox support team
502 Bad Gateway Loadfox is down or servers are upgraded at the moment
503 Service Unavailable The Loadfox servers are up, but overloaded with requests. Try again later.
504 Gateway Timeout Loadfox servers are up, but your request takes too much time

Messages

Each message (request body / response body) MUST be in JSON format. A response from the LoadFox API always contain the following fields:

Name Type Description
timestamp STRING Timestamp (UTC) when response is created by responding server
version STRING Version number
requestId STRING Unique identifier assigned to your request

On success the response contains “data” field that contains the result of the operation. On error the response contains a field “error” with the following fields:

Name Type Description
type STRING Error category, e.g. authentication, validation, …
code NUMBER A numeric code of the error
message STRING Description of the error
Operations
Alarms
POST /alarms/createAlarm
POST /alarms/updateAlarm
POST /alarms/getAlarm
POST /alarms/findAlarms
POST /alarms/deleteAlarm
createAlarm
POST /alarms/createAlarm

Create a new alarm.

If you’re using a company authentication token you must provide the user ID of one of your users in the request.

Request body

Responses

200 200

OK

Example 1
Example 2

A minimal valid alarm data required to create an alarm when logged in as a user.

POST https://demo.loadfox.eu/api/partners/v1/alarms/createAlarm HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
  "enabled": true,
  "evaluationInterval": "IMMEDIATE",
  "maxEmailsPerDay": 10,
  "name": "alarm name",
  "filters": {
    "bodyType": {
      "values": [
        "TARPAULIN",
        "JUMBO"
      ]
    },
    "loadType": {
      "values": [
        "PALETTE",
        "CAGE"
      ]
    },
    "distanceTotal": {
      "min": 10,
      "max": 100
    },
    "durationDrive": {
      "min": 1,
      "max": 10
    },
    "length": {
      "min": 10,
      "max": 200
    },
    "priceTotal": {
      "min": 10
    },
    "weight": {
      "min": 100,
      "max": 1000
    },
    "priceDistance": {
      "min": 1
    },
    "loadSource": {
      "sources": [
        "PARTNERS",
        "COMPANY"
      ]
    }
  },
  "orders": [
    {
      "field": "CREATE_TIMESTAMP",
      "direction": "ASC"
    }
  ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.0.0"
    "data": {
        "alarmId": "A-ABC1234",
        "userId": "U-ZYYUZJ-8ZX",
        "enabled": true,
        "evaluationInterval": "IMMEDIATE",
        "maxEmailsPerDay": 10,
        "name": "alarm name",
        "filters": {
            "bodyType": {
                "values": [
                    "TARPAULIN",
                    "JUMBO"
                ]
            },
            "loadType": {
                "values": [
                    "PALETTE",
                    "CAGE"
                ]
            },
            "distanceTotal": {
                "min": 10,
                "max": 100
            },
            "durationDrive": {
                "min": 1,
                "max": 10
            },
            "length": {
                "min": 10,
                "max": 200
            },
            "priceTotal": {
                "min": 10
            },
            "weight": {
                "min": 100,
                "max": 1000
            },
            "priceDistance": {
                "min": 1
            },
            "loadSource": {
                "sources": [
                    "PARTNERS",
                    "COMPANY"
                ]
            }
        },
        "orders": [
            {
                "field": "CREATE_TIMESTAMP",
                "direction": "ASC"
            }
        ]
    }
}

An example of alarm with all filters filled.

POST https://demo.loadfox.eu/api/partners/v1/alarms/createAlarm HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "enabled": true,
    "evaluationInterval": "IMMEDIATE",
    "maxEmailsPerDay": 10,
    "name": "random name",
    "filters": {
        "bodyType": {
            "values": [
                "TARPAULIN",
                "JUMBO"
            ]
        },
        "companyId": {
            "superset": [
                "C-ABCDEF"
            ]
        },
        "destinationTimeWindowBegin": {
            "max": 1000000
        },
        "distanceTotal": {
            "min": 10,
            "max": 100
        },
        "durationDrive": {
            "min": 1,
            "max": 10
        },
        "equipmentType": {
            "values": [
                "LIFTING_PLATFORM",
                "WALKING_FLOOR"
            ]
        },
        "length": {
            "min": 10,
            "max": 200
        },
        "loadId": {
            "intersect": [
                "L-ABCDEF"
            ],
            "superset": [
                "L-FEDCBA"
            ]
        },
        "loadSource": {
            "sources": [
                "PARTNERS",
                "GROUPS",
                "COMPANY"
            ],
            "groupIds": [
                "G-ABCDEF"
            ]
        },
        "loadType": {
            "values": [
                "PALETTE",
                "CAGE"
            ]
        },
        "onlySinglePartner": true,
        "onlySinglePickUpAndDropOff": true,
        "onlySingleRamp": true,
        "priceDistance": {
            "min": 1
        },
        "priceTotal": {
            "min": 10
        },
        "location": {
            "source": {
                "areaFilters": [
                    {
                        "country": "DE",
                        "areaCode": "80"
                    }
                ],
                "pointFilters": [
                    {
                        "locationId": "LC-BBBBB1"
                    }
                ],
                "circleFilters": [
                    {
                        "locationId": "LC-BBBBB2",
                        "radius": 25
                    }
                ],
                "countryFilters": [
                    {
                        "country": "PL"
                    }
                ]
            },
            "destination": {
                "areaFilters": [
                    {
                        "country": "DE",
                        "areaCode": "80"
                    }
                ],
                "pointFilters": [
                    {
                        "locationId": "LC-BBBBB1"
                    }
                ],
                "circleFilters": [
                    {
                        "locationId": "LC-BBBBB2",
                        "radius": 25
                    }
                ],
                "countryFilters": [
                    {
                        "country": "PL"
                    }
                ]
            }
        },
        "sourceTimeWindowEnd": {
            "min": 1000000
        },
        "transportType": {
            "values": [
                "DANGEROUS_GOODS",
                "PALLET_EXCHANGE"
            ]
        },
        "weight": {
            "min": 100,
            "max": 1000
        }
    },
    "orders": [
        {
            "field": "CREATE_TIMESTAMP",
            "direction": "ASC"
        },
        {
            "field": "DESTINATION_TIMESTAMP_BEGIN",
            "direction": "DESC"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.0.0",
    "data": {
        "alarmId": "A-ABC1234",
        "enabled": true,
        "evaluationInterval": "IMMEDIATE",
        "maxEmailsPerDay": 10,
        "name": "random name",
        "filters": {
            "bodyType": {
                "values": [
                    "TARPAULIN",
                    "JUMBO"
                ]
            },
            "companyId": {
                "superset": [
                    "C-ABCDEF"
                ]
            },
            "destinationTimeWindowBegin": {
                "max": 1000000
            },
            "distanceTotal": {
                "min": 10,
                "max": 100
            },
            "durationDrive": {
                "min": 1,
                "max": 10
            },
            "equipmentType": {
                "values": [
                    "LIFTING_PLATFORM",
                    "WALKING_FLOOR"
                ]
            },
            "length": {
                "min": 10,
                "max": 200
            },
            "loadId": {
                "intersect": [
                    "L-ABCDEF"
                ],
                "superset": [
                    "L-FEDCBA"
                ]
            },
            "loadSource": {
                "sources": [
                    "PARTNERS",
                    "GROUPS",
                    "COMPANY"
                ],
                "groupIds": [
                    "G-ABCDEF"
                ]
            },
            "loadType": {
                "values": [
                    "PALETTE",
                    "CAGE"
                ]
            },
            "onlySinglePartner": true,
            "onlySinglePickUpAndDropOff": true,
            "onlySingleRamp": true,
            "priceDistance": {
                "min": 1
            },
            "priceTotal": {
                "min": 10
            },
            "location": {
                "source": {
                    "areaFilters": [
                        {
                            "country": "DE",
                            "areaCode": "80"
                        }
                    ],
                    "pointFilters": [
                        {
                            "locationId": "LC-BBBBB1"
                        }
                    ],
                    "circleFilters": [
                        {
                            "locationId": "LC-BBBBB2",
                            "radius": 25
                        }
                    ],
                    "countryFilters": [
                        {
                            "country": "PL"
                        }
                    ]
                },
                "destination": {
                    "areaFilters": [
                        {
                            "country": "DE",
                            "areaCode": "80"
                        }
                    ],
                    "pointFilters": [
                        {
                            "locationId": "LC-BBBBB1"
                        }
                    ],
                    "circleFilters": [
                        {
                            "locationId": "LC-BBBBB2",
                            "radius": 25
                        }
                    ],
                    "countryFilters": [
                        {
                            "country": "PL"
                        }
                    ]
                }
            },
            "sourceTimeWindowEnd": {
                "min": 1000000
            },
            "transportType": {
                "values": [
                    "DANGEROUS_GOODS",
                    "PALLET_EXCHANGE"
                ]
            },
            "weight": {
                "min": 100,
                "max": 1000
            }
        },
        "orders": [
            {
                "field": "CREATE_TIMESTAMP",
                "direction": "ASC"
            },
            {
                "field": "DESTINATION_TIMESTAMP_BEGIN",
                "direction": "DESC"
            }
        ]
    }
}
updateAlarm
POST /alarms/updateAlarm

Update an existing alarm.

The user to whom the alarm is associated with cannot be changed.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/alarms/updateAlarm HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "alarmId": "A-ABC1234",
    "enabled": true,
    "evaluationInterval": "HOURLY",
    "maxEmailsPerDay": 10,
    "name": "hourly offers",
    "filters": {
        "bodyType": {
            "values": [
                "TARPAULIN",
                "JUMBO"
            ]
        },
        "loadType": {
            "values": [
                "PALETTE",
                "CAGE"
            ]
        },
        "distanceTotal": {
            "min": 10,
            "max": 100
        },
        "durationDrive": {
            "min": 1,
            "max": 10
        },
        "length": {
            "min": 10,
            "max": 200
        },
        "priceTotal": {
            "min": 10
        },
        "weight": {
            "min": 100,
            "max": 1000
        },
        "priceDistance": {
            "min": 1
        },
        "loadSource": {
            "sources": [
                "PARTNERS",
                "COMPANY"
            ]
        }
    },
    "orders": [
        {
            "field": "CREATE_TIMESTAMP",
            "direction": "ASC"
        }
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.0.0"
    "data": {
        "alarmId": "A-ABC1234",
        "userId": "U-ZYYUZJ-8ZX",
        "enabled": true,
        "evaluationInterval": "HOURLY",
        "maxEmailsPerDay": 10,
        "name": "hourly offers",
        "filters": {
            "bodyType": {
                "values": [
                    "TARPAULIN",
                    "JUMBO"
                ]
            },
            "loadType": {
                "values": [
                    "PALETTE",
                    "CAGE"
                ]
            },
            "distanceTotal": {
                "min": 10,
                "max": 100
            },
            "durationDrive": {
                "min": 1,
                "max": 10
            },
            "length": {
                "min": 10,
                "max": 200
            },
            "priceTotal": {
                "min": 10
            },
            "weight": {
                "min": 100,
                "max": 1000
            },
            "priceDistance": {
                "min": 1
            },
            "loadSource": {
                "sources": [
                    "PARTNERS",
                    "COMPANY"
                ]
            }
        },
        "orders": [
            {
                "field": "CREATE_TIMESTAMP",
                "direction": "ASC"
            }
        ]
    }
}
getAlarm
POST /alarms/getAlarm

Get a single alarm by its ID.

Request body

request

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/alarms/getAlarm HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "alarmId": "A-ABC1234"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.0.0",
    "data": {
        "alarmId": "A-ABC1234",
        "userId": "U-ZYYUZJ-8ZX",
        "enabled": true,
        "evaluationInterval": "IMMEDIATE",
        "maxEmailsPerDay": 10,
        "name": "random name",
        "filters": {
            "bodyType": {
                "values": [
                    "TARPAULIN",
                    "JUMBO"
                ]
            },
            "companyId": {
                "superset": [
                ]
            },
            "destinationTimeWindowBegin": {
                "max": 1000000
            },
            "distanceTotal": {
                "min": 10,
                "max": 100
            },
            "durationDrive": {
                "min": 1,
                "max": 10
            },
            "equipmentType": {
                "values": [
                    "LIFTING_PLATFORM",
                    "WALKING_FLOOR"
                ]
            },
            "length": {
                "min": 10,
                "max": 200
            },
            "loadId": {
                "intersect": [
                ],
                "superset": [
                ]
            },
            "loadSource": {
                "sources": [
                    "PARTNERS",
                    "GROUPS",
                    "COMPANY"
                ],
                "groupIds": [
                ]
            },
            "loadType": {
                "values": [
                    "PALETTE",
                    "CAGE"
                ]
            },
            "onlySinglePartner": true,
            "onlySinglePickUpAndDropOff": true,
            "onlySingleRamp": true,
            "priceDistance": {
                "min": 1
            },
            "priceTotal": {
                "min": 10
            },
            "location": {
                "source": {
                    "areaFilters": [
                        {
                            "country": "DE",
                            "areaCode": "80"
                        }
                    ],
                    "pointFilters": [
                        {
                            "locationId": "LC-BBBBB1"
                        }
                    ],
                    "circleFilters": [
                        {
                            "locationId": "LC-BBBBB2",
                            "radius": 25
                        }
                    ],
                    "countryFilters": [
                        {
                            "country": "PL"
                        }
                    ]
                },
                "destination": {
                    "areaFilters": [
                        {
                            "country": "DE",
                            "areaCode": "80"
                        }
                    ],
                    "pointFilters": [
                        {
                            "locationId": "LC-BBBBB1"
                        }
                    ],
                    "circleFilters": [
                        {
                            "locationId": "LC-BBBBB2",
                            "radius": 25
                        }
                    ],
                    "countryFilters": [
                        {
                            "country": "PL"
                        }
                    ]
                }
            },
            "sourceTimeWindowEnd": {
                "min": 1000000
            },
            "transportType": {
                "values": [
                    "DANGEROUS_GOODS",
                    "PALLET_EXCHANGE"
                ]
            },
            "weight": {
                "min": 100,
                "max": 1000
            }
        },
        "orders": [
            {
                "field": "CREATE_TIMESTAMP",
                "direction": "ASC"
            },
            {
                "field": "DESTINATION_TIMESTAMP_BEGIN",
                "direction": "DESC"
            }
        ]
    }
}
findAlarms
POST /alarms/findAlarms

Find all matching alarms.

Request body

Responses

200 200

OK

Example 1

Example for querying for alarms of a given user when logged in as a company.

POST https://demo.loadfox.eu/api/partners/v1/alarms/findAlarms HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "userId": "U-ABC123DEF456"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.0.0",
    "data": [
        {
            "alarmId": "A-ABC1234",
            "userId": "U-ABC123DEF456",
            "enabled": true,
            "evaluationInterval": "IMMEDIATE",
            "maxEmailsPerDay": 10,
            "name": "alarm name",
            "filters": {
                "bodyType": {
                    "values": [
                        "TARPAULIN",
                        "JUMBO"
                    ]
                },
                "loadType": {
                    "values": [
                        "PALETTE",
                        "CAGE"
                    ]
                },
                "distanceTotal": {
                    "min": 10,
                    "max": 100
                },
                "durationDrive": {
                    "min": 1,
                    "max": 10
                },
                "length": {
                    "min": 10,
                    "max": 200
                },
                "priceTotal": {
                    "min": 10
                },
                "weight": {
                    "min": 100,
                    "max": 1000
                },
                "priceDistance": {
                    "min": 1
                },
                "loadSource": {
                    "sources": [
                        "PARTNERS",
                        "COMPANY"
                    ]
                }
            },
            "orders": [
                {
                    "field": "CREATE_TIMESTAMP",
                    "direction": "ASC"
                }
            ]
        },
        {
            "alarmId": "A-XYZ0987",
            "userId": "U-ABC123DEF456",
            "enabled": true,
            "evaluationInterval": "IMMEDIATE",
            "maxEmailsPerDay": 10,
            "name": "alarm name",
            "filters": {
                "bodyType": {
                    "values": [
                        "TARPAULIN",
                        "JUMBO"
                    ]
                },
                "loadType": {
                    "values": [
                        "PALETTE",
                        "CAGE"
                    ]
                },
                "distanceTotal": {
                    "min": 10,
                    "max": 100
                },
                "durationDrive": {
                    "min": 1,
                    "max": 10
                },
                "length": {
                    "min": 10,
                    "max": 200
                },
                "priceTotal": {
                    "min": 10
                },
                "weight": {
                    "min": 100,
                    "max": 1000
                },
                "priceDistance": {
                    "min": 1
                },
                "loadSource": {
                    "sources": [
                        "PARTNERS",
                        "COMPANY"
                    ]
                }
            },
            "orders": [
                {
                    "field": "CREATE_TIMESTAMP",
                    "direction": "ASC"
                }
            ]
        }
    ]
}
deleteAlarm
POST /alarms/deleteAlarm

Delete an existing alarm.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/alarms/deleteAlarm HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "alarmId": "A-ABC1234"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.0.0",
    "data": {
        "alarmId": "A-ABC1234",
        "userId": "U-ZYYUZJ-8ZX",
        "enabled": true,
        "evaluationInterval": "IMMEDIATE",
        "maxEmailsPerDay": 10,
        "name": "alarm name",
        "filters": {
            "bodyType": {
                "values": [
                    "TARPAULIN",
                    "JUMBO"
                ]
            },
            "loadType": {
                "values": [
                    "PALETTE",
                    "CAGE"
                ]
            },
            "distanceTotal": {
                "min": 10,
                "max": 100
            },
            "durationDrive": {
                "min": 1,
                "max": 10
            },
            "length": {
                "min": 10,
                "max": 200
            },
            "priceTotal": {
                "min": 10
            },
            "weight": {
                "min": 100,
                "max": 1000
            },
            "priceDistance": {
                "min": 1
            },
            "loadSource": {
                "sources": [
                    "PARTNERS",
                    "COMPANY"
                ]
            }
        },
        "orders": [
            {
                "field": "CREATE_TIMESTAMP",
                "direction": "ASC"
            }
        ]
    }
}
Authentication

Auth Controller

POST /auth/getCompanyToken
POST /auth/getUserToken
getCompanyToken
POST /auth/getCompanyToken

Create a company authentication token

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/auth/getCompanyToken HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "applicationId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "applicationSecret": "11c4ef2b-2e26-4a57-9a11-0ceff4d302f2",
    "companyId": "C-ABC123DEF456",
    "companySecret": "XqHc6L7wRYBBGp1jZ2ir"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "expirationTimestamp": "2017-06-28 11:57:25",
        "token": "9612bf04-5567-11e8-2540-0ed53219718b"
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
getUserToken
POST /auth/getUserToken

Create a user authentication token

Application ID and secret should be provided in the request body.

For backwards compatibility: If 'applicationId' is missing from the request body, we try to read it from header 'X-App-Id'. If 'applicationSecret' is missing from the request body, it will be read from header 'X-App-Secret'. This behavior guarantees backward compatibility but might be removed in the next major update of the API.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/auth/getUserToken HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "applicationId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "applicationSecret": "11c4ef2b-2e26-4a57-9a11-0ceff4d302f2",
    "email": "max.mustermann@company.com",
    "password": "Test1234!"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "expirationTimestamp": "2017-06-28 11:57:25",
        "token": "9612bf04-5567-11e8-2540-0ed53219718b"
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
Groups

Group Controller

POST /groups/findGroups
POST /groups/getGroup
findGroups
POST /groups/findGroups

Get a list of groups matching provided search criteria. Only groups your company belongs to can be requested, groupId/name are interpreted as wildcard by default.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/groups/findGroups HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "groupId": "G-ABC123DEF456",
    "name": "Group-ABC"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": [
        {
            "groupId": "G-ABC123DEF456",
            "name": "Beverages"
        }
    ],
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
getGroups
POST /groups/getGroup

Get a single group by unique groupId. Only groups your company belongs to can be requested.

Request body

request

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/groups/getGroup HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "groupId": "G-ABC123DEF456"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "groupId": "G-ABC123DEF456",
        "name": "Beverages"
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
Loads

Load Controller

POST /loads/bookLoads
POST /loads/createLoad
POST /loads/deleteLoad
POST /loads/findLoads
POST /loads/getLoad
bookLoads
POST /loads/bookLoads

Book one or more loads. By specifying multiple load IDs it's possible to book an entire offer in one transaction. If one load cannot be booked, none will be booked at all.

Only users can book loads. If you're using a company authentication token you must provide the user ID of one of your users in the request.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/loads/bookLoads HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "loadIds": [
        "L-ABCD1234"
    ],
    "permutation": "AA"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": [
        {
            "createdBy": {
                "company": {
                    "city": "München",
                    "companyId": "C-DEF567",
                    "country": "DE",
                    "name": "Fast Transports Inc.",
                    "streetName": "Fuchsstraße",
                    "streetNumber": "12",
                    "website": "https://www.fast-transports.de",
                    "zipCode": 80807
                },
                "companyId": "C-DEF567",
                "email": "tim.dispatcher@fast-transports.de",
                "fax": "+49891234562",
                "firstname": "Tim",
                "gender": "MALE",
                "lastname": "Dispatcher",
                "locale": "de",
                "mobile": "+49150123456",
                "phone": "+49891234561",
                "position": "MANAGING_DIRECTOR",
                "userId": "U-DEF567-KK3"
            },
            "loads": [
                {
                    "actions": [
                        {
                            "type": "PICKUP",
                            "locationId": "LC-ABC1234",
                            "location": {
                                "city": {
                                    "de": "Bedburg",
                                    ...
                                },
                                "country": "DE",
                                "locationId": "LC-ABC1234",
                                "postcode": "50181"
                            },
                            "begin": "2017-09-16 08:00:00",
                            "end": "2017-09-16 12:00:00",
                            "duration": 3600,
                            "ramps": 1
                        },
                        {
                            "type": "DROPOFF",
                            "locationId": "LC-EFG56789",
                            "location": {
                                "city": {
                                    "de": "Hannover",
                                    ...
                                },
                                "country": "DE",
                                "locationId": "LC-EFG56789",
                                "postcode": "30159"
                            },
                            "begin": "2017-09-17 06:00:00",
                            "end": "2017-09-17 14:00:00",
                            "duration": 3600,
                            "ramps": 1
                        }
                    ],
                    "bodyTypes": [
                        "TARPAULIN"
                    ],
                    "comment": "Driver needs additional certification X and Y",
                    "companyId": "C-ABC123DEF456",
                    "currency": "EUR",
                    "equipmentTypes": [
                        "COIL_TROUGH"
                    ],
                    "groupIds": [],
                    "groups": [],
                    "internalId": "SomeInternalIdentifier",
                    "length": 1320,
                    "loadId": "L-ABC123DEF567",
                    "loadType": "PALETTE",
                    "loadVisibility": "PARTNERS",
                    "locationVisibility": "FULL",
                    "pickupId": "SomePickupIdentifier",
                    "price": 30000,
                    "priceType": "NEGOTIABLE",
                    "quantity": 20,
                    "state": "BOOKED",
                    "transportTypes": [
                        "DANGEROUS_GOODS"
                    ],
                    "user": {
                        "company": {
                            "city": "München",
                            "companyId": "C-ABC123",
                            "country": "DE",
                            "name": "Mustermann Transports Inc.",
                            "streetName": "Oskar-Schlemmer-Straße",
                            "streetNumber": "19-21",
                            "website": "https://www.mustermann-transports.com",
                            "zipCode": 80807
                        },
                        "companyId": "C-ABC123",
                        "email": "max.mustermann@example.org",
                        "fax": "+49891234562",
                        "firstname": "Max",
                        "gender": "MALE",
                        "lastname": "Mustermann",
                        "locale": "de",
                        "mobile": "+49150123456",
                        "phone": "+49891234561",
                        "position": "MANAGING_DIRECTOR",
                        "userId": "U-ABC123-AB1"
                    },
                    "userId": "U-ABC123-AB1",
                    "weight": 14000
                }
            ],
            "status": "BOOKED_ON_THE_ROAD",
            "timestamp": "2017-09-15 11:57:25",
            "transactionId": "T-ABC123",
            "type": "LOAD_FORWARDED"
        }
    ],
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
createLoad
POST /loads/createLoad

Create a new load

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/loads/createLoad HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "actions": [
        {
            "type": "PICKUP",
            "locationId": "LC-BXKLC8C",
            "begin": "2018-09-16 08:00:00",
            "end": "2018-09-16 12:00:00",
            "duration": 3600,
            "ramps": 1
        },
        {
            "type": "DROPOFF",
            "locationId": "LC-BXKLBJN",
            "begin": "2018-09-17 06:00:00",
            "end": "2018-09-17 14:00:00",
            "duration": 3600,
            "ramps": 1
        }
    ],
    "bodyTypes": [
        "BOX_BODY"
    ],
    "comment": "Driver needs additional certification X and Y",
    "currency": "EUR",
    "equipmentTypes": [
        "REEFER"
    ],
    "internalId": "internal ID 123",
    "length": 1320,
    "loadType": "PALETTE",
    "locationVisibility": "FULL",
    "pickupId": "SomePickupIdentifier",
    "price": 30000,
    "priceType": "NEGOTIABLE",
    "quantity": 20,
    "transportTypes": [
        "PALLET_EXCHANGE"
    ],
	"visibilitySteps": [
		{
			"date": "2018-09-14 06:00:00",
			"visibility": "COMPANY",
			"groupIds": []
		},
		{
			"date": "2018-09-14 15:00:00",
			"visibility": "PARTNERS",
			"groupIds": []
		}
	],
    "userId": "U-ZYYUZJ-8ZX",
    "weight": 14000
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
	"timestamp": "2018-09-14 06:12:00",
	"version": "1.0.0",
	"requestId": "41ab5f39-176e-4aff-a3e7-0b3b3793a9fa",
	"data": {
		"loadId": "L-VFP75I",
		"userId": "U-ZYYUZJ-8ZX",
		"companyId": "C-ZYYUZJ",
		"price": 30000,
		"priceType": "NEGOTIABLE",
		"currency": "EUR",
		"weight": 14000,
		"length": 1320,
		"actions": [
			{
				"type": "PICKUP",
				"location": {
					"city": {
						"de": "München",
						"en": "Munich",
						"pl": "München"
					},
					"country": "DE",
					"locationId": "LC-BXKLC8C",
					"postcode": "80331"
				},
				"locationId": "LC-BXKLC8C",
				"begin": "2018-09-16 08:00:00",
				"end": "2018-09-16 12:00:00",
				"duration": 3600,
				"ramps": 1
			},
			{
				"type": "DROPOFF",
				"location": {
					"city": {
						"de": "Nürnberg",
						"en": "Nuremberg",
						"pl": "Nürnberg"
					},
					"country": "DE",
					"locationId": "LC-BXKLBJN",
					"postcode": "90402"
				},
				"locationId": "LC-BXKLBJN",
				"begin": "2018-09-17 06:00:00",
				"end": "2018-09-17 14:00:00",
				"duration": 3600,
				"ramps": 1
			}
		],
		"locationVisibility": "FULL",
		"loadType": "PALETTE",
		"quantity": 20,
		"pickupId": "SomePickupIdentifier",
		"internalId": "internal ID 123",
		"comment": "Driver needs additional certification X and Y",
		"loadVisibility": "COMPANY",
		"groupIds": [],
		"state": "OPEN",
		"bodyTypes": [
			"BOX_BODY"
		],
		"equipmentTypes": [
			"REEFER"
		],
		"transportTypes": [
			"PALLET_EXCHANGE"
		],
    	"visibilitySteps": [
    		{
    			"date": "2018-09-14 06:00:00",
    			"visibility": "COMPANY",
    			"groupIds": []
    		},
    		{
    			"date": "2018-09-14 15:00:00",
    			"visibility": "PARTNERS",
    			"groupIds": []
    		}
    	]
	}
}
deleteLoad
POST /loads/deleteLoad

Delete a single load by unique loadId. Only loads owned by your company can be deleted.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/loads/deleteLoad HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "loadId": "L-ABC123"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "loadId": "L-ABC123",
        ...
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
findLoads
POST /loads/findLoads

Get a list of loads matching provided search criteria.
Only loads owned by your company can be requested, loadId/userId/pickupId/internalId are interpreted as wildcard, price/currency/weight/length/quantity/state/loadType/visibility as exact match.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/loads/findLoads HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "internalId": "SomeInternalIdentifier"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": [
        {
            "actions": [
                {
                    "type": "PICKUP",
                    "locationId": "LC-BXKKQ6W",
                    "begin": "2017-09-16 08:00:00",
                    "end": "2017-09-16 12:00:00",
                    "duration": 3600,
                    "ramps": 1
                },
                {
                    "type": "DROPOFF",
                    "locationId": "LC-BXKJ76K",
                    "begin": "2017-09-17 06:00:00",
                    "end": "2017-09-17 14:00:00",
                    "duration": 3600,
                    "ramps": 1
                }
            ],
            "bodyTypes": [
                "BOX_BODY"
            ],
            "comment": "Driver needs additional certification X and Y",
            "currency": "EUR",
            "equipmentTypes": [
                "REEFER"
            ],
            "groupIds": [],
            "internalId": "internal ID 123",
            "length": 1320,
            "loadId": "L-ABC123",
            "loadType": "PALETTE",
            "loadVisibility": "GROUP",
            "locationVisibility": "FULL",
            "pickupId": "SomePickupIdentifier",
            "price": 30000,
            "priceType": "NEGOTIABLE",
            "quantity": 20,
            "transportTypes": [
                "PALLET_EXCHANGE"
            ],
            "userId": "U-ABC123DEF456",
            "weight": 14000
        }
    ],
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
getLoad
POST /loads/getLoad

Get a single load by unique loadId. Only loads owned by your company can be requested.

Request body

request

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/loads/getLoad HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "loadId": "L-ABC123"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "actions": [
            {
                "type": "PICKUP",
                "locationId": "LC-ABC1234",
                "location": {
                    "city": {
                        "de": "Bedburg",
                        ...
                    },
                    "country": "DE",
                    "locationId": "LC-ABC1234",
                    "postcode": "50181"
                },
                "begin": "2017-09-16 08:00:00",
                "end": "2017-09-16 12:00:00",
                "duration": 3600,
                "ramps": 1
            },
            {
                "type": "DROPOFF",
                "locationId": "LC-EFG56789",
                "location": {
                    "city": {
                        "de": "Hannover",
                        ...
                    },
                    "country": "DE",
                    "locationId": "LC-EFG56789",
                    "postcode": "30159"
                },
                "begin": "2017-09-17 06:00:00",
                "end": "2017-09-17 14:00:00",
                "duration": 3600,
                "ramps": 1
            }
        ],
        "bodyTypes": [
            "TARPAULIN"
        ],
        "comment": "Driver needs additional certification X and Y",
        "companyId": "C-ABC123DEF456",
        "currency": "EUR",
        "equipmentTypes": [
            "COIL_TROUGH"
        ],
        "groupIds": [],
        "groups": [],
        "internalId": "SomeInternalIdentifier",
        "length": 1320,
        "loadId": "L-ABC123DEF567",
        "loadType": "PALETTE",
        "loadVisibility": "PARTNERS",
        "locationVisibility": "FULL",
        "pickupId": "SomePickupIdentifier",
        "price": 30000,
        "priceType": "NEGOTIABLE",
        "quantity": 20,
        "state": "BOOKED",
        "transportTypes": [
            "DANGEROUS_GOODS"
        ],
        "user": {
            "company": {
                "city": "München",
                "companyId": "C-ABC123",
                "country": "DE",
                "name": "Mustermann Transports Inc.",
                "streetName": "Oskar-Schlemmer-Straße",
                "streetNumber": "19-21",
                "website": "https://www.mustermann-transports.com",
                "zipCode": 80807
            },
            "companyId": "C-ABC123",
            "email": "max.mustermann@example.org",
            "fax": "+49891234562",
            "firstname": "Max",
            "gender": "MALE",
            "lastname": "Mustermann",
            "locale": "de",
            "mobile": "+49150123456",
            "phone": "+49891234561",
            "position": "MANAGING_DIRECTOR",
            "userId": "U-ABC123-AB1"
        },
        "userId": "U-ABC123-AB1",
        "visibilitySteps": null,
        "weight": 14000
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
Locations

Location Controller

POST /locations/findLocations
POST /locations/getLocation
findLocations
POST /locations/findLocations

Get a list of locations matching provided search criteria.
All request body fields are interpreted as wildcard, e.g. 85 -> 85*, Münch -> Münch*
Search for city is case insensitive and in all available languages, e.g. searching for Munich or München will find similar locations.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/locations/findLocations HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "country": "DE",
    "postcode": "50"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": [
        {
            "city": {
                "de": "Bedburg",
                ...
            },
            "country": "DE",
            "locationId": "LC-BXKKQ6W",
            "postcode": "50181"
        },
        ...
    ],
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
getLocation
POST /locations/getLocation

Get a single location by unique locationId

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/locations/getLocation HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "locationId": "LC-BXKKQ6W"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "city": {
            "de": "Bedburg",
            ...
        },
        "country": "DE",
        "locationId": "LC-BXKKQ6W",
        "postcode": "50181"
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
Offers

Offer Controller

POST /offers/query
query
POST /offers/query

Query for available offers.

Request body

request

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/offers/query HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "filters": {
      "priceTotal": {
        "min": 20000
      }
    },
    "orders": [
        {
            "direction": "DESC",
            "field": "PRICE_DISTANCE"
        }
    ],
    "page": {
        "limit": 100,
        "offset": 0
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "offers": [
            {
                "bodyTypes": [
                    "PLATEAU"
                ],
                "createTimestamp": 1526225693517,
                "destinationLocationId": "LC-EFG56789",
                "destinationLocation": {
                    "city": {
                        "de": "Hannover",
                        ...
                    },
                    "country": "DE",
                    "locationId": "LC-EFG56789",
                    "postcode": "30159"
                },
                "destinationTimestampBegin": 1526564192517,
                "destinationTimestampEnd": 1526565693517,
                "distanceEmpty": 300,
                "distanceTotal": 1200,
                "durationDrive": 1,
                "durationTotalMax": 3000,
                "durationTotalMin": 120,
                "equipmentTypes": [
                    "WALKING_FLOOR"
                ],
                "length": 1320,
                "loadTypes": [
                    "PALETTE"
                ],
                "loads": [
                    {
                        "actions": [
                            {
                                "type": "PICKUP",
                                "locationId": "LC-ABC1234",
                                "location": {
                                    "city": {
                                        "de": "Bedburg",
                                        ...
                                    },
                                    "country": "DE",
                                    "locationId": "LC-ABC1234",
                                    "postcode": "50181"
                                },
                                "begin": "2017-09-16 08:00:00",
                                "end": "2017-09-16 12:00:00",
                                "duration": 3600,
                                "ramps": 1
                            },
                            {
                                "type": "DROPOFF",
                                "locationId": "LC-EFG56789",
                                "location": {
                                    "city": {
                                        "de": "Hannover",
                                        ...
                                    },
                                    "country": "DE",
                                    "locationId": "LC-EFG56789",
                                    "postcode": "30159"
                                },
                                "begin": "2017-09-17 06:00:00",
                                "end": "2017-09-17 14:00:00",
                                "duration": 3600,
                                "ramps": 1
                            }
                        ],
                        "bodyTypes": [
                            "TARPAULIN"
                        ],
                        "comment": "Driver needs additional certification X and Y",
                        "companyId": "C-ABC123DEF456",
                        "currency": "EUR",
                        "equipmentTypes": [
                            "COIL_TROUGH"
                        ],
                        "groupIds": [],
                        "groups": [],
                        "internalId": "SomeInternalIdentifier",
                        "length": 1320,
                        "loadId": "L-ABC123DEF567",
                        "loadType": "PALETTE",
                        "loadVisibility": "PARTNERS",
                        "locationVisibility": "FULL",
                        "pickupId": "SomePickupIdentifier",
                        "price": 30000,
                        "priceType": "NEGOTIABLE",
                        "quantity": 20,
                        "state": "BOOKED",
                        "transportTypes": [
                            "DANGEROUS_GOODS"
                        ],
                        "user": {
                            "company": {
                                "city": "München",
                                "companyId": "C-ABC123",
                                "country": "DE",
                                "name": "Mustermann Transports Inc.",
                                "streetName": "Oskar-Schlemmer-Straße",
                                "streetNumber": "19-21",
                                "website": "https://www.mustermann-transports.com",
                                "zipCode": 80807
                            },
                            "companyId": "C-ABC123",
                            "email": "max.mustermann@example.org",
                            "fax": "+49891234562",
                            "firstname": "Max",
                            "gender": "MALE",
                            "lastname": "Mustermann",
                            "locale": "de",
                            "mobile": "+49150123456",
                            "phone": "+49891234561",
                            "position": "MANAGING_DIRECTOR",
                            "userId": "U-ABC123-AB1"
                        },
                        "userId": "U-ABC123-AB1",
                        "weight": 14000
                    }
                ],
                "numberActions": 8,
                "numberDropoffs": 2,
                "numberPartners": 1,
                "numberPickups": 2,
                "numberRamps": 4,
                "numberRampsDropoff": 2,
                "numberRampsPickup": 2,
                "permutation": "AABB",
                "priceDistance": 200,
                "priceTotal": 54999,
                "sourceLocationId": "LC-ABC1234",
                "sourceLocation": {
                    "city": {
                        "de": "Bedburg",
                        ...
                    },
                    "country": "DE",
                    "locationId": "LC-ABC1234",
                    "postcode": "50181"
                },
                "sourceTimestampBegin": 1526453192517,
                "sourceTimestampEnd": 1526456192517,
                "transportTypes": [
                    "PALLET_EXCHANGE"
                ],
                "weight": 14000
            }
        ],
        "page": {
            "frame": 100,
            "limit": 100,
            "offset": 50,
            "total": 200000
        }
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
Transactions

Transaction Controller

POST /transactions/findTransactions
findTransactions
POST /transactions/findTransactions

Get a list of all matching transactions.
Transactions are returned in reverse chronological order and no more than 100 entries will be returned in one call. It is possible to paginate through all data by using the ‘beforeTimestamp’ filter.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/transactions/findTransactions HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": [
        {
            "createdBy": {
                "company": {
                    "city": "München",
                    "companyId": "C-DEF567",
                    "country": "DE",
                    "name": "Fast Transports Inc.",
                    "streetName": "Fuchsstraße",
                    "streetNumber": "12",
                    "website": "https://www.fast-transports.de",
                    "zipCode": 80807
                },
                "companyId": "C-DEF567",
                "email": "tim.dispatcher@fast-transports.de",
                "fax": "+49891234562",
                "firstname": "Tim",
                "gender": "MALE",
                "lastname": "Dispatcher",
                "locale": "de",
                "mobile": "+49150123456",
                "phone": "+49891234561",
                "position": "MANAGING_DIRECTOR",
                "userId": "U-DEF567-KK3"
            },
            "loads": [
                {
                    "actions": [
                        {
                            "type": "PICKUP",
                            "locationId": "LC-ABC1234",
                            "location": {
                                "city": {
                                    "de": "Bedburg",
                                    ...
                                },
                                "country": "DE",
                                "locationId": "LC-ABC1234",
                                "postcode": "50181"
                            },
                            "begin": "2017-09-16 08:00:00",
                            "end": "2017-09-16 12:00:00",
                            "duration": 3600,
                            "ramps": 1
                        },
                        {
                            "type": "DROPOFF",
                            "locationId": "LC-EFG56789",
                            "location": {
                                "city": {
                                    "de": "Hannover",
                                    ...
                                },
                                "country": "DE",
                                "locationId": "LC-EFG56789",
                                "postcode": "30159"
                            },
                            "begin": "2017-09-17 06:00:00",
                            "end": "2017-09-17 14:00:00",
                            "duration": 3600,
                            "ramps": 1
                        }
                    ],
                    "bodyTypes": [
                        "TARPAULIN"
                    ],
                    "comment": "Driver needs additional certification X and Y",
                    "companyId": "C-ABC123DEF456",
                    "currency": "EUR",
                    "equipmentTypes": [
                        "COIL_TROUGH"
                    ],
                    "groupIds": [],
                    "groups": [],
                    "internalId": "SomeInternalIdentifier",
                    "length": 1320,
                    "loadId": "L-ABC123DEF567",
                    "loadType": "PALETTE",
                    "loadVisibility": "PARTNERS",
                    "locationVisibility": "FULL",
                    "pickupId": "SomePickupIdentifier",
                    "price": 30000,
                    "priceType": "NEGOTIABLE",
                    "quantity": 20,
                    "state": "BOOKED",
                    "transportTypes": [
                        "DANGEROUS_GOODS"
                    ],
                    "user": {
                        "company": {
                            "city": "München",
                            "companyId": "C-ABC123",
                            "country": "DE",
                            "name": "Mustermann Transports Inc.",
                            "streetName": "Oskar-Schlemmer-Straße",
                            "streetNumber": "19-21",
                            "website": "https://www.mustermann-transports.com",
                            "zipCode": 80807
                        },
                        "companyId": "C-ABC123",
                        "email": "max.mustermann@example.org",
                        "fax": "+49891234562",
                        "firstname": "Max",
                        "gender": "MALE",
                        "lastname": "Mustermann",
                        "locale": "de",
                        "mobile": "+49150123456",
                        "phone": "+49891234561",
                        "position": "MANAGING_DIRECTOR",
                        "userId": "U-ABC123-AB1"
                    },
                    "userId": "U-ABC123-AB1",
                    "weight": 14000
                }
            ],
            "status": "BOOKED_ON_THE_ROAD",
            "timestamp": "2017-09-15 11:57:25",
            "transactionId": "T-ABC123",
            "type": "LOAD_FORWARDED"
        }
    ],
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
Users

User Controller

POST /users/createUser
POST /users/findUsers
POST /users/getUser
createUser
POST /users/createUser

Create a new user

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/users/createUser HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "email": "max.mustermann@example.org",
    "fax": "+49891234562",
    "firstname": "Max",
    "gender": "MALE",
    "lastname": "Mustermann",
    "locale": "de",
    "mobile": "+49150123456",
    "phone": "+49891234561",
    "position": "MANAGING_DIRECTOR"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "companyId": "C-UR2AN9",
        "email": "max.mustermann@example.org",
        "fax": "+49891234562",
        "firstname": "Max",
        "gender": "MALE",
        "lastname": "Mustermann",
        "locale": "de",
        "mobile": "+49150123456",
        "phone": "+49891234561",
        "position": "MANAGING_DIRECTOR",
        "userId": "U-GHZ123H"
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
findUsers
POST /users/findUsers

Get a list of users matching provided search criteria. Only users of your company can be requested, userId/firstname/lastname/email/phone/fax/mobile are interpreted as wildcard, gender/locale as exact match.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/users/findUsers HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "email": "max.mustermann@example.org"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": [
        {
            "companyId": "C-UR2AN9",
            "email": "max.mustermann@example.org",
            "fax": "+49891234562",
            "firstname": "Max",
            "gender": "MALE",
            "lastname": "Mustermann",
            "locale": "de",
            "mobile": "+49150123456",
            "phone": "+49891234561",
            "position": "MANAGING_DIRECTOR",
            "userId": "U-GHZ123H"
        }
    ],
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
getUser
POST /users/getUser

Get a single user by unique userId. Only users of your company can be requested.

Request body

request

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/users/getUser HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "userId": "U-GHZ123H"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "companyId": "C-UR2AN9",
        "email": "max.mustermann@example.org",
        "fax": "+49891234562",
        "firstname": "Max",
        "gender": "MALE",
        "lastname": "Mustermann",
        "locale": "de",
        "mobile": "+49150123456",
        "phone": "+49891234561",
        "position": "MANAGING_DIRECTOR",
        "userId": "U-GHZ123H"
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
Webhooks

Webhook Controller

POST /webhooks/getWebhook
POST /webhooks/setWebhook
getWebhook
POST /webhooks/getWebhook

Get the current url used by the LoadFox system to deliver events.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/webhooks/getWebhook HTTP/1.1 

Content-Type: application/json;charset=utf-8

{}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "url": "https://tms.schnelle-transporte.de/loadfox-callback"
    },
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
setWebhook
POST /webhooks/setWebhook

Set a URL for the LoadFox system to send events to. See EventModel for a description of the events.

Events are sent again until the system gets a success confirmation in the response from the partner. The receiver of events must acknowledge the delivery by returning HTTP status code 200 (response-body is ignored).
This avoids problems during maintenance time windows and if the partner system or parts of it are unreachable. A minium-once approach is used, meaning an event is sent at least one time but can be sent multiple times. Thus, the partner system needs to be able to handle duplicates. Events contain a „requestId“ field that can be used for duplicate detection.

Request body

Responses

200 200

OK

Example 1
POST https://demo.loadfox.eu/api/partners/v1/webhooks/setWebhook HTTP/1.1 

Content-Type: application/json;charset=utf-8

{
    "url": "https://tms.schnelle-transporte.de/loadfox-callback"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {},
    "requestId": "2842bf04-4944-11e8-842f-0ed5f89f718b",
    "timestamp": "2017-06-28 11:57:25",
    "version": "1.2.3"
}
Type Definitions
ActionModel

This entity represents a loading / unloading (pick-up / drop-off) step of a tour.

Object
begin
string required

Earliest datetime when it is possible to start the action

Example:
2017-09-16 10:00:00
duration
integer int32 required

Duration (normal / planned) for the action in seconds

Example:
3600
end
string required

Latest datetime when it is possible to start the action

Example:
2017-09-17 10:00:00
location
locationId
string required

Id of location (deprecated, use ‘location.locationId’)

Example:
LC-ABC1234
ramps
integer int32 required

Number of loading / unloading actions at this location

Example:
1
type
string required

Type of action

Enumeration:
PICKUP
DROPOFF
Example:
PICKUP
AlarmBodyTypeFilterModel
Object
values
Array required

Body types. At least body type must be specified.

string
Enumeration:
TARPAULIN
BOX_BODY
PLATEAU
MEGA
JUMBO
AlarmCompanyIdFilterModel

Filter by companies.

Object
superset
Array of string required

Only return offers with all loads from these companies. At least one company must be specified.

AlarmDestinationTimeWindowBeginFilterModel
Object
max
integer int64 required

Only return offers with a last drop-off time window beginning before this time (in milliseconds since unix epoch, inclusive).

AlarmDistanceTotalFilterModel
Object
max
integer int32 required

Only return offers with this maximum total drive distance (in kilometers, inclusive)

Min: 0
Max: 9,999
min
integer int32 required

Only return offers with this minimum total drive distance (in kilometers, inclusive)

Min: 0
Max: 9,999
AlarmDurationDriveFilterModel
Object
max
integer int32 required

Only return offers with this maximum driving duration (in hours, inclusive)

Min: 0
Max: 47
min
integer int32 required

Only return offers with this minimum driving duration (in hours, inclusive)

Min: 0
Max: 47
AlarmEquipmentTypeFilterModel
Object
values
Array required

Equipment types

string
Enumeration:
REEFER
LIFTING_PLATFORM
ON_BOARD_FORKLIFT
WALKING_FLOOR
COIL_TROUGH
AlarmLengthFilterModel
Object
max
integer int32 required

Only return offers with this maximum loading meter requirement (in centimeters, inclusive)

Min: 10
Max: 2,110
min
integer int32 required

Only return offers with this minimum loading meter requirement (in centimeters, inclusive)

Min: 10
Max: 2,110
AlarmLoadIdFilterModel

Filter by loads.

Only one filter option can be used.

Object
intersect
Array of string

Only return offers with one or more of these loads

superset
Array of string

Only return offers with all of these loads

AlarmLoadSourceFilterModel
Object
groupIds
Array of string

List of groups (group IDs), needed/considered only if ‘sources’ is set to GROUP

sources
Array required

Visibility of the loads, either

  • COMPANY (only visible to employees of your company),
  • GROUP (visible to members of specified group(s) and employees of your company),
  • PUBLIC (visible to all partners).
At least one value must be specified.

Example:
GROUP
string
Enumeration:
COMPANY
GROUPS
PARTNERS
AlarmLoadTypeFilterModel
Object
values
Array required

Load types. At least one load type must be specified.

string
Enumeration:
PALETTE
UNIT
CAGE
AlarmLocationAreaModel
Object
areaCode
string required

Area code of an area within a country.

country
string required

Supported country code to filter by.

Enumeration:
DE
PL
AT
BE
NL
LU
FR
IT
ES
SI
SK
CZ
HU
DK
AlarmLocationCircleModel
Object
locationId
string required

Location id of a location to filter by.

radius
integer int32 required

Radius of a circle around zip code in kilometers (inclusive) that should be considered.Valid values are 0, 999 and multiplies of 25. Any other value will be rounded to the nearest multiply of 25.

Min: 0
Max: 999
AlarmLocationCountryModel
Object
country
string required

Supported country code to filter by.

Enumeration:
DE
PL
AT
BE
NL
LU
FR
IT
ES
SI
SK
CZ
HU
DK
AlarmLocationFilterModel

Filter by locations.

Any combination of filters can be specified.

Object
areaFilters
circleModels
countryModels
pointFilters
AlarmLocationPointModel
Object
locationId
string required

Location id of a location to filter by.

AlarmLocationsFilterModel
AlarmModel

The details of the alarm

Object
alarmId
string required

The ID of the alarm

Example:
A-ABC1234
enabled
boolean required

If the alarm is enabled or disabled

Example:
true
evaluationInterval
string required

In which interval the alarm should be evaluated.
The intervals are always relative to the full hour e.g. HALF_HOURLY would be 9:00 and 9:30 independent of when the alarm was created.

Enumeration:
IMMEDIATE
QUARTER_HOURLY
HALF_HOURLY
HOURLY
DAILY
Example:
HALF_HOURLY
filters
maxEmailsPerDay
string required

The maximum number of emails that should be send our for this alarm per day.

Enumeration:
1
5
10
15
25
UNLIMITED
Example:
10
name
string required

Name of the alarm

Example:
My hourly offers
orders
Array of AlarmOfferOrderModel required

Specifies the sort order of the results. The sequence of fields in the list and their individual sort order determine the overall order in which offers are returned.

Example:
[
  {
    "field" : "PRICE_DISTANCE",
    "direction" : "ASC"
  }
]
userId
string required

The ID of the user that owns this alarm.

AlarmOfferFiltersModel

The filter model provides many filter options to select the offers of interest.

Only specify filters that you intent to use. Example:

{
  “priceTotal”: {
    “min”: 20000
  }
}

Currently, alarms do not support all features of the offers query API.

Object
bodyType
destinationTimeWindowBegin
loadType
onlySinglePartner
boolean

Do not combine multiple partners within an offer. Default is false.

onlySinglePickUpAndDropOff
boolean

Return only offers with loads with a single pickup location and single drop off location. Default is false.

onlySingleRamp
boolean

Return only offers with one ramp per un-/loading location. Default is false.

AlarmOfferOrderModel

An instruction to sort based on this field

Object
direction
string required

Sort order

Enumeration:
ASC
DESC
field
string required

Field name

Enumeration:
CREATE_TIMESTAMP
PRICE_TOTAL
PRICE_DISTANCE
LENGTH
WEIGHT
SOURCE_TIMESTAMP_BEGIN
SOURCE_LOCATION_POSTCODE
DESTINATION_LOCATION_POSTCODE
DESTINATION_TIMESTAMP_BEGIN
DISTANCE_TOTAL
NUMBER_PICKUPS
NUMBER_DROPOFFS
NUMBER_PARTNERS
DURATION_DRIVE
AlarmPriceDistanceFilterModel
Object
min
integer int32 required

Only return offers with this minimum price per kilometer (in €-cent / km, inclusive)

Min: 0
Max: 999,900
AlarmPriceTotalFilterModel
Object
min
integer int32 required

Only return offers with this minimum total price (in €-cent, inclusive)

Min: 0
Max: 999,900
AlarmSourceTimeWindowEndFilterModel
Object
min
integer int64 required

Only return offers with a first pick-up time window ending after this time (in milliseconds since unix epoch, inclusive)

AlarmTransportTypeFilterModel
Object
values
Array required

Transport types

string
Enumeration:
DANGEROUS_GOODS
PALLET_EXCHANGE
AlarmWeightFilterModel
Object
max
integer int32 required

Only return offers with this maximum weight (in kilograms, inclusive)

Min: 100
Max: 27,000
min
integer int32 required

Only return offers with this minimum weight (in kilograms, inclusive)

Min: 100
Max: 27,000
BodyTypeFilterModel
Object
mode
string required

If this filter should include or exclude the specified values.

Enumeration:
INCLUDE
EXCLUDE
values
Array required

Body types

string
Enumeration:
TARPAULIN
BOX_BODY
PLATEAU
MEGA
JUMBO
BookLoadsRequest

A load booking request.

Object
loadIds
Array of string required

A list of load IDs that should be booked.

Example:
[
  "L-ABC123DEF567"
]
permutation
string

The permutation specifies in which sequence the loads are to be transported. For example, AABB stands for: pick-up A, drop-off of A, pick-up B, and finally drop-off B. ABBA stands for: pick-up A, pick-up B, drop-off B, and finally drop-off A. Thus, permutations express all possibilities for sequential and parallel transport for up to three loads.

The permutation is used to check if this combination of loads is feasible. Only feasible combinations can be booked.

Enumeration:
AA
AABB
ABBA
AABBCC
ABCCBA
AABCCB
ABBACC
ABBCCA
Example:
AABB
userId
string

ID of the user that should be used for the booking. Only users belonging to your company can be used. Required if a company authentication token is used and must be undefined otherwise.

Example:
U-ABC123DEF456
BookLoadsResponse

Returns the transaction details with all details of a booking (including contact details of the load owner/giver). Possible error codes:

  • 1000: VALIDATION - A parameter/field has a syntax validation error or is required, but not present.
  • 1001: VALIDATION - A userId was provided while using a user authentication token.
  • 3001: RELATION - User with this ID not found or does not belong to your company.
  • 3002: RELATION - Load with this ID not found.
  • 4000: LOGIC - The state of a load does not allow a booking (e.g. it’s already booked).
  • 4001: LOGIC - The combination of loads is not feasible.

Object
data

Data object provided in success case

error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
CompanyIdFilterModel

Filter by companies.

Multiple of the filter options (disjoint, intersect, superset) can be used at the same time, but at least one is required.

Object
disjoint
Array of string

Only return offers with no loads from these companies

intersect
Array of string

Only return offers with one or more loads from these companies

superset
Array of string

Only return offers with all loads from these companies

CompanyModel

The entity represents a company in the Loadfox system.

Object
city
Object

Name of the city per locale (de,en,pl)

additional properties
string
companyId
string

Identifier of the company

Example:
C-ABC123
country
string

Country code (ISO 3166 Alpha-2)

Example:
DE
name
string

Name of the company

Example:
Mustermann Transports Inc.
streetName
string

Street name

Example:
Oskar-Schlemmer-Straße
streetNumber
string

Street number

Example:
19-21
website
string

Website

Example:
https://www.mustermann-transports.com
zipCode
string

ZIP code

Example:
80807
CreateActionModel

This entity represents a loading / unloading (pick-up / drop-off) step of a tour.

The time window defined by begin/end must be at least as long as the duration. Thus, it’s the time window for the complete action, not the time window when it’s possible to start the action.

Object
begin
string required

Earliest datetime when it is possible to start the action

Example:
2017-09-16 10:00:00
duration
integer int32 required

Duration (normal / planned) for the action in seconds

Example:
3600
end
string required

Latest datetime when it is possible to start the action

Example:
2017-09-17 10:00:00
locationId
string required

Id of location (deprecated)

Example:
LC-ABC1234
ramps
integer int32 required

Number of loading / unloading actions at this location

Example:
1
type
string required

Type of action

Enumeration:
PICKUP
DROPOFF
Example:
PICKUP
CreateAlarmRequest

The details of the alarm that should be created.

Object
enabled
boolean required

If the alarm is enabled or disabled

Example:
true
evaluationInterval
string required

In which interval the alarm should be evaluated.
The intervals are always relative to the full hour e.g. HALF_HOURLY would be 9:00 and 9:30 independent of when the alarm was created.

Enumeration:
IMMEDIATE
QUARTER_HOURLY
HALF_HOURLY
HOURLY
DAILY
Example:
HALF_HOURLY
filters
maxEmailsPerDay
string required

The maximum number of emails that should be send our for this alarm per day.

Enumeration:
1
5
10
15
25
UNLIMITED
Example:
10
name
string required

Name of the alarm.

Min length: 1
Max length: 50
Example:
My hourly offers
orders
Array of AlarmOfferOrderModel required

Specifies the sort order of the results. The sequence of fields in the list and their individual sort order determine the overall order in which offers are returned. At least one sort order must be specified.

Example:
[
  {
    "field" : "PRICE_DISTANCE",
    "direction" : "ASC"
  }
]
userId
string

ID of the user for whom the alarm is created. Only users belonging to your company can be used. Required if a company authentication token is used and must be undefined otherwise.

Example:
U-ABC123DEF456
CreateAlarmResponse

Returns the newly created alarm.
Possible error codes:

  • 1000: VALIDATION - A parameter has a syntax validation error or is required, but not present.
  • 1001: VALIDATION - A userId was provided while using a user authentication token.
  • 3001: RELATION - User with this ID not found or does not belong to your company.

Object
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
CreateLoadRequest

The details of the load that should be created.

Object
actions
Array of CreateActionModel required

Pick up and drop off locations with additional information, sorted in chronological order

bodyTypes
Array required

Possible truck body-types to ship the load, minimum one must be provided

Example:
[
  "TARPAULIN",
  "BOX_BODY",
  "JUMBO"
]
string
Enumeration:
TARPAULIN
BOX_BODY
PLATEAU
MEGA
JUMBO
comment
string

Additional comment/information to the load

Example:
Driver needs additional certification X and Y
currency
string required

Price currency (ISO 4217 currency code)

Enumeration:
EUR
Example:
EUR
equipmentTypes
Array

Equipment(s) needed to ship the load

string
Enumeration:
REEFER
LIFTING_PLATFORM
ON_BOARD_FORKLIFT
WALKING_FLOOR
COIL_TROUGH
groupIds
Array of string

Deprecated. Please use the 'visibilitySteps' property instead.

List of groups (group IDs), needed/considered only if LoadVisibility is set to 'GROUPS'
Example:
[
  "G-TR54K",
  "G-MBQ543"
]
internalId
string

Identifier of the load in customer system, must be unique per company if provided

Example:
SomeInternalIdentifier
length
integer int32 required

Load length in cm e.g. 13,2ldm would be 1320

Example:
1320
loadType
string required

Type of load

Enumeration:
PALETTE
UNIT
CAGE
Example:
PALETTE
loadVisibility
string

Deprecated. Please use the 'visibilitySteps' property instead.

The visibility of a load can be either:
  • COMPANY (only visible to employees of your company),
  • GROUPS (visible to members of the specified group(s) and employees of your company),
  • PARTNERS (visible to all partners).
Partners that you have blacklisted will never see any load of you.
Enumeration:
COMPANY
PARTNERS
GROUPS
Example:
PARTNERS
locationVisibility
string

Visibility of Pickup/Dropoff locations. If only PARTIAL visible we will only show a Zipcode-Region instead of full Zipcode. Location become fully visible for the partner who booked the load.
This property has been deprecated and no longer used. Locations will always have full visibility.

Enumeration:
PARTIAL
FULL
Example:
FULL
pickupId
string

Some identifier of the load for the truck driver at the pickup location

Example:
SomePickupIdentifier
price
integer int32 required

Base-Price of load in smallest currency unit e.g. Cent

Example:
30000
priceType
string required

Indicates if price is negotiable or fixed (negotiable means bidding is possible)

Enumeration:
FIXED
NEGOTIABLE
Example:
NEGOTIABLE
quantity
integer int32 required

Number of units/cages/palettes (depends on LoadType)

Example:
20
transportTypes
Array

Additional transport restrictions that needs to be fulfilled to ship the load

string
Enumeration:
DANGEROUS_GOODS
PALLET_EXCHANGE
userId
string required

ID of user. If a company authentication token is used, it must be a user of the same company, otherwise the current user.

Example:
U-ABC123DEF456
visibilitySteps
Array of VisibilityStep required

A list of steps that define the visibility of a load. This sets the initial visibility of the load and allows to automatically change the visibility over time.

  • A visibility step becomes active when the specified date is reached and completely overrides the previously defined visibility (no additive behavior).
  • At least one visibility step must be in the past or on the current date (thus, there is always a defined visibility for the current date).
  • There can't be two visibility steps on the same date.
  • The order of elements in this list is irrelevant.
  • A maximum of five visibility steps can defined.
Example:
[
  {
    "date" : "2018-09-15 06:00:00",
    "visibility" : "PARTNERS"
  }
]
weight
integer int32 required

Load weight in kg e.g. 14t would be 14000

Example:
14000
CreateLoadResponse

Returns the newly created load. Possible error codes:

  • 1000: VALIDATION - A parameter/field has a syntax validation error or is required, but not present.
  • 3001: RELATION - User with this ID not found.
  • 3002: RELATION - Group with this ID not found.
  • 3003: RELATION - Location with this ID not found.
  • 4000: LOGIC - Load not possible to drive, because of load windows / driving time / legal obligations.

Object
data
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
CreateTimestampFilterModel
Object
max
integer int64

Only return offers created before this time (in milliseconds since unix epoch, inclusive).

min
integer int64

Only return offers created after this time (in milliseconds since unix epoch, inclusive).

CreateUserRequest

The details of the user that should be created.

Object
email
string required

E-Mail of user, unique in the Loadfox system

Example:
max.mustermann@example.org
fax
string

Fax number, international GSM format

Example:
+49891234562
firstname
string required

Firstname of user

Example:
Max
gender
string required

Gender of user

Enumeration:
MALE
FEMALE
Example:
MALE
lastname
string required

Lastname of user

Example:
Mustermann
locale
string required

ISO 639-1-alpha2 language code

Enumeration:
de
en
pl
Example:
de
mobile
string

Mobile phone number, international GSM format

Example:
+49150123456
phone
string required

Landline phone number, international GSM format

Example:
+49891234561
position
string

Job title / position of user

Enumeration:
MANAGING_DIRECTOR
FLEET_MANAGER
DEPARTMENT_MANAGER
AUTHORIZED_OFFICER
DISPATCHER
OTHER
Example:
MANAGING_DIRECTOR
CreateUserResponse

Returns the newly created user.
Possible error codes:

  • 1000: VALIDATION - A parameter has a syntax validation error or is required, but not present.
  • 2000: CONSTRAINT - A user with this email already exists.

Object
data
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
DeleteAlarmRequest

The details of the alarm deletion request.

Object
alarmId
string required

The ID of the alarm that should be deleted

Example:
A-ABC1234
DeleteAlarmResponse

Possible error codes:

  • 1000: VALIDATION - A parameter has a syntax validation error or is required, but not present.
  • 3000: RELATION - Alarm with this ID was not found or belongs to another user/company.

Object
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
DeleteLoadRequest
Object
loadId
string required

The ID of the load to delete

DeleteLoadResponse

The confirmation of deletion. Possible error codes:

  • 2000: CONSTRAINT - Load can not be deleted, because it’s booked or reserved.
  • 3000: RELATION - Load with this ID was not found.

Object
data
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
DestinationTimeWindowBeginFilterModel
Object
max
integer int64

Only return offers with a last drop-off time window beginning before this time (in milliseconds since unix epoch, inclusive).

min
integer int64

Only return offers with a last drop-off time window beginning after this time (in milliseconds since unix epoch, inclusive).

DestinationTimeWindowEndFilterModel
Object
max
integer int64

Only return offers with a last drop-off time window ending before this time (in milliseconds since unix epoch, inclusive).

min
integer int64

Only return offers with a last drop-off time window ending after this time (in milliseconds since unix epoch, inclusive).

DistanceDeltaFilterModel

Filter by distance delta. The distance delta is the total distance of this offer minus the sum of the distances for each contained load.

Object
max
integer int32

Only return offers with this maximum distance delta (in kilometers, inclusive)

min
integer int32

Only return offers with this minimum distance delta (in kilometers, inclusive).

DistanceEmptyFilterModel
Object
max
integer int32

Only return offers with this maximum empty drive distance (in kilometers, inclusive)

min
integer int32

Only return offers with this minimum empty drive distance (in kilometers, inclusive)

DistanceTotalFilterModel
Object
max
integer int32

Only return offers with this maximum total drive distance (in kilometers, inclusive)

min
integer int32

Only return offers with this minimum total drive distance (in kilometers, inclusive)

DurationDriveFilterModel
Object
max
integer int32

Only return offers with this maximum driving duration (in minutes, inclusive)

min
integer int32

Only return offers with this minimum driving duration (in minutes, inclusive)

DurationTotalMaxFilterModel
Object
max
integer int32

Only return offers with this maximum total duration maximum (in minutes, inclusive)

min
integer int32

Only return offers with this minimum total duration maximum (in minutes, inclusive)

DurationTotalMinFilterModel
Object
max
integer int32

Only return offers with this maximum total duration minimum (in minutes, inclusive)

min
integer int32

Only return offers with this minimum total duration minimum (in minutes, inclusive)

EquipmentTypeFilterModel
Object
mode
string required

If this filter should include or exclude the specified values.

Enumeration:
INCLUDE
EXCLUDE
values
Array required

Equipment types

string
Enumeration:
REEFER
LIFTING_PLATFORM
ON_BOARD_FORKLIFT
WALKING_FLOOR
COIL_TROUGH
Error
Object
code
integer int32 required

Error code - Identifier of the error defined per operation

Example:
4001
message
string required

Error message - Description of error (always english, should be only used for testing integration)

Example:
Missing field or invalid syntax
type
string required

Error type / category

Enumeration:
VALIDATION
LOGIC
RELATION
CONSTRAINT
Example:
VALIDATION
EventModel

An event is sent whenever a load is changed (state change, e.g. BOOKED/RESERVED/DELETED or changes to the load performed through the LoadFox website).

Object
action
string

The action that has been triggered

Enumeration:
CREATED
UPDATED
DELETED
RESERVED
UNRESERVED
BOOKED
UNBOOKED
EXPIRED
Example:
RESERVED
data
event
string

Type of the event

Enumeration:
EVENT_LOAD
Example:
EVENT_LOAD
requestId
string

Unique identifier of the event (identical on resend)

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
version
string

Server version

Example:
1.2.3
FindAlarmsRequest
Object
userId
string

Only show alarms belonging to a certain user. If not set, all alarms that you’re allowed to see will be returned.

Example:
U-ABC123DEF456
FindAlarmsResponse

Returns all matching alarms.

Object
data
Array of AlarmModel

Data object provided in success case

error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
FindGroupsRequest
Object
groupId
string

The ID of the group to search for (interpreted as wildcard)

Example:
G-ABC123DEF456
name
string

Name of the group to search for (interpreted as wildcard)

Example:
Group-ABC
FindGroupsResponse

List of groups matching search criteria, can be empty, number of results is limited to 100.

Object
data
Array of GroupModel

Data object provided in success case

error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
FindLoadsRequest

The loads filter criteria.

Object
currency
string

Price currency

Enumeration:
EUR
Example:
EUR
internalId
string

Identifier of the load in customer system, must be unique per company if provided

Example:
SomeInternalIdentifier
length
integer int32

Load length in cm e.g. 13,2ldm would be 1320

Example:
1320
loadId
string

The ID of the load

Example:
L-ABC123DEF567
loadType
string

Type of load

Enumeration:
PALETTE
UNIT
CAGE
Example:
PALETTE
loadVisibility
string

Visibility of the load, either

  • COMPANY (only visible to employees of your company),
  • GROUP (visible to members of specified group(s) and employees of your company),
  • PUBLIC (visible to all partners).
Partners that you have blacklisted will never see any load of you

Enumeration:
COMPANY
PARTNERS
GROUPS
Example:
GROUP
pickupId
string

Some identifier of the load for the truck driver at the pickup location

Example:
SomePickupIdentifier
price
integer int32

Base-Price of load in smallest currency unit e.g. Cent

Example:
30000
quantity
integer int32

Number of units/cages/palettes (depends on LoadType)

Example:
20
state
string

Current state of the load

Enumeration:
OPEN
BOOKED
RESERVED
EXPIRED
DELETED
Example:
BOOKED
userId
string

ID of user the load belongs to

Example:
U-ABC123DEF456
weight
integer int32

Load weight in kg e.g. 14t would be 14000

Example:
14000
FindLoadsResponse

List of loads matching search criteria, can be empty, number of results is limited to 100.

Object
data
Array of LoadModel

Data object provided in success case

error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
FindLocationsRequest

The location search criteria.

Object
city
string

Name of city

Example:
02345
country
string

Country code ISO 3166 Alpha-2

Enumeration:
DE
PL
AT
BE
NL
LU
FR
IT
ES
SI
SK
CZ
HU
DK
Example:
DE
locationId
string

ID of location

Example:
LC-ABC1234
postcode
string

Canonized postcode without country specific formatting

Example:
02345
FindLocationsResponse

List of locations matching search criteria, can be empty, number of results is limited to 100.
Possible error codes:

  • 1000: VALIDATION - Field is missing or invalid value.

Object
data
Array of LocationModel

Data object provided in success case

error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
FindTransactionsRequest
Object
beforeTimestamp
string

Return only transactions that have been performed before the given timestamp (exclusive).

Example:
2017-06-28 11:57:25
FindTransactionsResponse

The retrieved transactions.

Object
data

Data object provided in success case

error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
FindUsersRequest

A user search request.

Object
email
string

Search by email

Example:
max.mustermann@example.org
fax
string

Fax number, international GSM format

Example:
+49891234562
firstname
string

Search by firstname

Example:
Max
gender
string

Search by gender

Enumeration:
MALE
FEMALE
Example:
MALE
lastname
string

Search by lastname

Example:
Mustermann
locale
string

Search by locale

Enumeration:
de
en
pl
Example:
de
mobile
string

Mobile phone number, international GSM format

Example:
+49150123456
phone
string

Landline phone number, international GSM format

Example:
+49891234561
position
string

Search by position

Enumeration:
MANAGING_DIRECTOR
FLEET_MANAGER
DEPARTMENT_MANAGER
AUTHORIZED_OFFICER
DISPATCHER
OTHER
Example:
MANAGING_DIRECTOR
userId
string

Search by a unique userId

Example:
U-GHZ123H
FindUsersResponse

List of users matching search criteria, can be empty, number of results is limitied to 100.
Possible error codes:

  • 1000: VALIDATION - Field missing or invalid value.

Object
data
Array of UserModel

Data object provided in success case

error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GetAlarmRequest
Object
alarmId
string required

The ID of the alarm

Example:
A-ABC1234
GetAlarmResponse

Returns the specified alarm.
Possible error codes:

  • 1000: VALIDATION - A parameter has a syntax validation error or is required, but not present.
  • 3000: RELATION - Alarm with this ID was not found or belongs to another user/company.

Object
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GetCompanyTokenRequest
Object
applicationId
string required

Your application ID (provided by LoadFox)

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
applicationSecret
string required

Your application secret (provided by LoadFox)

Example:
11c4ef2b-2e26-4a57-9a11-0ceff4d302f2
companyId
string required

The ID of the company to login with

Example:
C-ABC123DEF456
companySecret
string required

The secret of the company to login with

Example:
XqHc6L7wRYBBGp1jZ2ir
GetCompanyTokenResponse

The generated authentication token. Possible error codes:

  • 1000: VALIDATION - A parameter/field has a syntax validation error or is required, but not present.
  • 4000: LOGIC - Invalid credentials.

Object
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GetGroupRequest
Object
groupId
string required

ID of the group

Example:
G-ABC123DEF456
GetGroupResponse

A single group. Possible error codes:

  • 3000: RELATION - No group with this ID found.

Object
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GetLoadRequest
Object
loadId
string required

The ID of the load to return

GetLoadResponse

Possible error codes:

  • 3000: RELATION - No load found with this loadId.

Object
data
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GetLocationRequest
Object
locationId
string required

ID of location

Example:
LC-ABC1234
GetLocationResponse

The retrieved location. Possible error codes:

  • 3000: RELATION - No location found with this ID.

Object
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GetUserRequest
Object
userId
string required

ID of user

Example:
U-GHZ123H
GetUserResponse

The retrieved user. Possible error codes:

  • 3000: RELATION - No user found with this ID.

Object
data
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GetUserTokenRequest
Object
applicationId
string required

Your application ID (provided by LoadFox)

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
applicationSecret
string required

Your application secret (provided by LoadFox)

Example:
11c4ef2b-2e26-4a57-9a11-0ceff4d302f2
email
string required

The email address of the user to login with

Example:
max.mustermann@company.com
password
string required

The password of the user to login with

Example:
Test1234!
GetUserTokenResponse

The generated authentication token. Possible error codes:

  • 1000: VALIDATION - A parameter/field has a syntax validation error or is required, but not present.
  • 4000: LOGIC - Invalid credentials.
  • 4001: LOGIC - User disabled/blocked.

Object
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GetWebhookRequest
Object
GetWebhookResponse

The current URL used for event delivery. Possible error codes:

  • 3000: RELATION - No endpoint set.

Object
data
error
requestId
string required

Unique identifier of your request for debugging/analysis

Example:
2842bf04-4944-11e8-842f-0ed5f89f718b
timestamp
string required

Timestamp (UTC Timezone) the request was processed on LoadFox server

Example:
2017-06-28 11:57:25
version
string required

Partner API Version on LoadFox server processing your request

Example:
1.2.3
GroupModel

The group entity represents a subset of companies (partners) on the platform. On load creation you can decide if you only want to make the load visible for every company, only your company or for one or more groups.
Groups can be used to cluster companies, for example by

  • sector (e.g. beverages),
  • company or industry certification,
  • your already existing partners you prefer before contracting another company,
  • or shipper contract (all companies allowed to have a contract with shipper Y).
Groups are currently managed only by LoadFox, so please contact us if you want to be part of a specific group or if we can create for you own groups matching your requirements. (We plan to make different types of groups in the future which can be administrated also by yourself either on the frontend and/or by API)

Object
groupId
string required

ID of the group

Example:
G-ABC123DEF456
name
string required

Name of the group

Example:
Beverages
LengthFilterModel

Filter by required loading meters