Get route contracts list

Downloading a list of contracts created in selected route.

The route-id identification number in request can be taken by downloading the routes list.

GET
/ext/contracts-api/v1/routes/{route-id}/contracts

Request Authorization

Every request MUST include a valid access token obtained during the user authorization process, provided using the Bearer token scheme in the Authorization header.

Request Header

GET /ext/contracts-api/v1/routes/{route-id}/contracts HTTP/1.1 
Host: api.platform.trans.eu 
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token) 
Api-key: {unique_app_api-key}

Request Parameters (Query)

Pagination

By default, 25 results are download. You can change the number of results with the limit parameter, and you can skip fetching the initial results with the offset parameter.

/ext/contracts-api/v1/routes/{route-id}/contracts?limit=15           // downloading first 15 results
/ext/contracts-api/v1/routes/{route-id}/contracts?limit=10&offset=10 // downloading the second page for pages of size 10

Response Fields

Attribute	Type	Example	Description
contracts	Array of Objects		List of contracts assigned to route
contracts.carrier	Object		Carrier assigned to the contract
contracts.carrier.company	Object		Carrier company details
contracts.carrier.company.id	Int	567321	Carrier company Id
contracts.carrier.company.name	String	“EkoTransporter”	Carrier company name
contracts.carrier.contact_persons	Array of Objects		Carrier contact persons
contracts.carrier.contact_persons.channels	Array of Strings		Contact channels
contracts.carrier.contact_persons.employee	Object		Contact person details
contracts.carrier.contact_persons.employee.account_id	Int	771476	Contact person internal Id
contracts.carrier.contact_persons.employee.family_name	String	Miller	Contact person family name
contracts.carrier.contact_persons.employee.given_name	String	Michael	Contact person given name
contracts.carrier.contact_persons.employee.trans_id	String	“1012334–1”	Contact person TransId
contracts.id	String	“23ba734b-5b1f-4be1-9b82-a91e4dff6551”	Contract id
contracts.order_terms	Object		Order terms
contracts.order_terms.additional_terms	String	“additional terms text”	Additional terms for contract
contracts.order_terms.automatic_order_sending	Boolean	True	Automatic creation of a confirmed order when the carrier accepts the freight
contracts.order_terms.insurance	Object		Insurance requirements
contracts.order_terms.insurance.load	Object		Value of loads
contracts.order_terms.insurance.load.currency	String	“eur”	Loads value currency
contracts.order_terms.insurance.load.value	Int	12000	Value of loads
contracts.order_terms.insurance.third_party	Object		Required insurance value
contracts.order_terms.insurance.third_party.currency	String	“eur”	Insurance value currency
contracts.order_terms.insurance.third_party.value	Int	6000	Insurance value
contracts.order_terms.monitoring	Object		GPS monitoring
contracts.order_terms.monitoring.required	Boolean	True	If `True`, required GPS monitoring if technically possible
contracts.order_terms.payment_period	Object		Payment period
contracts.order_terms.payment_period.value	Int	12	Number of days
contracts.order_terms.silent_confirmation	Object
contracts.order_terms.silent_confirmation.enabled	Boolean
contracts.order_terms.silent_confirmation.time	Object
contracts.order_terms.silent_confirmation.time.unit_code	String
contracts.order_terms.silent_confirmation.time.user_unit_code	String
contracts.order_terms.silent_confirmation.time.value	Int
contracts.period	Object		Cooperation period
contracts.period.from	String	“2026–04-07T15:30:00+02:00”	Start of cooperation
contracts.period.to	String	null	End of cooperation. Possible value `null` for indefinitely.
contracts.planned_shipments	Object		Planned shipments in the contract
contracts.planned_shipments.periods	Array of Objects		Periods list
contracts.planned_shipments.periods.from	String	“2027–01-01T00:00:00.000Z”	Start of period
contracts.planned_shipments.periods.to	String	“2027–12-31T23:59:59.000Z”	End of period
contracts.planned_shipments.periods.value	Int		Number of shipments in period
contracts.planned_shipments.type	String	“expected”	Type of shipments. Available values: `required`, `expected`, `no_more_than`.
contracts.planned_shipments.unit	String	“km”	Unit of shipments. Available values: `shipment`, `ton`, `km`.
contracts.planned_shipments.value	Int	500	Total number of shipments in the contract
contracts.pricing	Object		Pricing for contract
contracts.pricing.negotiable	Boolean	True	Enabling price negotiation with carrier
contracts.pricing.price	Object		Price. Object occurs in all pricing types except `pallets`.
contracts.pricing.price.currency	String	“eur”	Price currency
contracts.pricing.price.value	Float	3000	Price value
contracts.pricing.price_list	Array of Objects		Price list. Object occurs only for pricing type `pallets`
contracts.pricing.price_list.price	Object		Price
contracts.pricing.price_list.price.currency	String	“eur”	Price currency
contracts.pricing.price_list.price.value	Float	232	Price value
contracts.pricing.price_list.range	Object		Range of pallets for contract
contracts.pricing.price_list.range.from	Int	1	Min value of pallets
contracts.pricing.price_list.range.to	int	20	Max value of pallets
contracts.pricing.settlement_basis	String	“distance_from_gps”	Surcharge basis. Required in pricing types: “km”, “ton”. Available values for “km”: `distance_declared_in_order_terms`, `distance_declared_by_carrier`, `distance_from_gps` Available values for “ton”: `loading`, `unloading`
contracts.pricing.type	String	“no_rate”	Type of pricing. Available values: `route`, `km`, `ton`, `pallets`, `linear`, `no_rate`. The `no_rate` value appears in flexible contracts, the remaining values appear in fixed contracts.
contracts.reference_number	String	“Kontrakt 23/2”	External reference number
contracts.route	Object		Route
contracts.route.id	String	“967dac7c-8812–41d9-8082–60ef1736d06c”	Route id
contracts.surcharges	Array of Objects		Surcharges
contracts.surcharges.currency	String	“eur”	Surcharges currency
contracts.surcharges.data
contracts.surcharges.description	String	“additional text”	Surcharge description
contracts.surcharges.id	String	“a1ebb289-e665-4b30-a580-d263552ef88c”	Surcharge Id
contracts.surcharges.is_active	Boolean	True	Surcharge activation status
contracts.surcharges.is_global	Boolean	False	If `True`, surcharge is from template
contracts.surcharges.kind	String	“grid”	Kind of surcharge. Available values: `grid`, `linear`, `value`
contracts.surcharges.schedules	Array of Objects		Surcharge schedules
contracts.surcharges.schedules.data	Object		Surcharge data
contracts.surcharges.schedules.data.matrix	Array of Objects		Data object for `additional_stop`, `baf`, `pallets_exchange` surcharge types.
contracts.surcharges.schedules.data.matrix.unit	String	“percentage”	Unit of data. Available values: `percentage`, `value`.
contracts.surcharges.schedules.data.matrix.value	Int	5	Data value
contracts.surcharges.schedules.data.currency	String	“eur”	Currency for data
surcharges.schedules.data.unit	String	“percentage”	Unit of data for `week_days` surcharge type. Available values: `percentage`, `value`.
surcharges.schedules.data.week_days	Array of Objects		Data object for `week_days` surcharge types.
surcharges.schedules.data.week_days.id	String	“1_monday”	Week day Id
surcharges.schedules.data.week_days.operations	Array of Objects		List of operations
surcharges.schedules.data.week_days.operations.type	String	“loading”	Operation type. Available values: `loading`, `unloading`
surcharges.schedules.data.week_days.operations.value	Int	5	Data Value
contracts.surcharges.schedules.timespan	Object		Surcharge schedule period
contracts.surcharges.schedules.timespan.from	String	“2026–04-30T15:30:00+02:00”	Start of schedule
contracts.surcharges.schedules.timespan.to	String	“2026–05-28T02:00:00+02:00”	End of schedule
contracts.surcharges.type	String	“baf”	Surcharge type. Available values: `additional_stop`, `baf`, `pallets_exchange`, `week_day`
total_items	Int	3	Number of contracts in response

Response Body

{
    "contracts": [
        {
            "id": "0dfc855d-ae8d-4d08-a8d4-a3375f8b78f9",
            "route": {
                "id": "3a378345-1939-48c1-bc71-639e0add8048"
            },
            "surcharges": [],
            "period": {},
            "carrier": {
                "company": {
                    "id": 1013865,
                    "name": "Carrier IIT 2"
                },
                "contact_persons": [
                    {
                        "employee": {
                            "account_id": 771476,
                            "given_name": "Max",
                            "family_name": "Miller",
                            "trans_id": "1013865-3"
                        }
                    }
                ]
            },
            "order_terms": {
                "automatic_order_sending": false,
                "payment_period": {
                    "value": null
                },
                "additional_terms": null,
                "insurance": {
                    "load": {
                        "currency": null,
                        "value": null
                    },
                    "third_party": {
                        "currency": null,
                        "value": null
                    }
                },
                "monitoring": {
                    "required": false
                },
                "silent_confirmation": {
                    "enabled": false,
                    "time": {
                        "unit_code": null,
                        "user_unit_code": null,
                        "value": null
                    }
                }
            },
            "planned_shipments": {
                "periods": [],
                "type": null,
                "unit": null,
                "value": null
            },
            "pricing": {
                "negotiable": true,
                "type": "no_rate",
                "price": {
                    "value": null,
                    "currency": null
                }
            },
            "reference_number": null
        },
        {
            "id": "89418bb3-4fe3-4c78-b6bb-fcbcd61234d4",
            "route": {
                "id": "3a378345-1939-48c1-bc71-639e0add8048"
            },
            "surcharges": [],
            "period": {},
            "carrier": {
                "company": {
                    "id": 567347,
                    "name": "Carrier 3"
                },
                "contact_persons": [
                    {
                        "employee": {
                            "account_id": 717862,
                            "given_name": "Alex",
                            "family_name": "Born",
                            "trans_id": "567347-1"
                        }
                    }
                ]
            },
            "order_terms": {
                "automatic_order_sending": false,
                "payment_period": {
                    "value": null
                },
                "additional_terms": null,
                "insurance": {
                    "load": {
                        "currency": null,
                        "value": null
                    },
                    "third_party": {
                        "currency": null,
                        "value": null
                    }
                },
                "monitoring": {
                    "required": false
                },
                "silent_confirmation": {
                    "enabled": false,
                    "time": {
                        "unit_code": null,
                        "user_unit_code": null,
                        "value": null
                    }
                }
            },
            "planned_shipments": {
                "periods": [],
                "type": null,
                "unit": null,
                "value": null
            },
            "pricing": {
                "negotiable": true,
                "type": "no_rate",
                "price": {
                    "value": null,
                    "currency": null
                }
            },
            "reference_number": null
        },
        {
            "id": "d68d9762-9a03-4209-8a8c-2acc15b8c83d",
            "route": {
                "id": "3a378345-1939-48c1-bc71-639e0add8048"
            },
            "surcharges": [
                {
                    "id": "58275662-573a-4a3f-a908-d5d5a2b39ffc",
                    "currency": "eur",
                    "description": "opis",
                    "kind": "linear",
                    "type": "additional_stop",
                    "is_global": true,
                    "is_active": true,
                    "schedules": [
                        {
                            "timespan": {
                                "from": "2026-04-17T11:14:40+02:00",
                                "to": "2026-04-30T23:59:59+02:00"
                            },
                            "data": {
                                "matrix": [
                                    {
                                        "unit": "value",
                                        "value": 6
                                    }
                                ]
                            }
                        }
                    ]
                }
            ],
            "period": {},
            "carrier": {
                "company": {
                    "id": 567347,
                    "name": "Carrier 3"
                },
                "contact_persons": [
                    {
                        "employee": {
                            "account_id": 717862,
                            "given_name": "Alex",
                            "family_name": "Born",
                            "trans_id": "567347-1"
                        }
                    }
                ]
            },
            "order_terms": {
                "automatic_order_sending": false,
                "payment_period": {
                    "value": 13
                },
                "additional_terms": null,
                "insurance": {
                    "load": {
                        "currency": null,
                        "value": null
                    },
                    "third_party": {
                        "currency": null,
                        "value": null
                    }
                },
                "monitoring": {
                    "required": false
                },
                "silent_confirmation": {
                    "enabled": false,
                    "time": {
                        "unit_code": null,
                        "user_unit_code": null,
                        "value": null
                    }
                }
            },
            "planned_shipments": {
                "periods": [],
                "type": null,
                "unit": null,
                "value": null
            },
            "pricing": {
                "negotiable": true,
                "type": "route",
                "price": {
                    "value": 56,
                    "currency": "eur"
                }
            },
            "reference_number": null
        }
    ],
    "total_items": 3
}

Client errors (code 400)

HTTP 4xx status codes indicate client errors, meaning that the request could not be processed due to an issue on the client side.