Create vehicle movement request for direct dispatch

Request

Creates a movement request for the provided vehicle and dispatches it directly to the chosen third-party logistics provider, bypassing the internal planning pool. The provider must exist and must support the requested transport method. Possible 400 error codes include THIRD_PARTY_LOGISTICS_PROVIDER_NOT_FOUND (the supplied id does not match a 3PL) and PROVIDER_CANNOT_FULFIL_MOVEMENT (the 3PL does not support the requested transport method).

Security

JigcarAPIAuth

Bodyapplication/jsonrequired

vehicleobject(Vehicle)required

originobject(OriginForCreateWith3pl)required

Origin shape for POST /v1/movement-requests/create-with-3pl. Identical to OriginForCreate plus the optional allowCollectionDateAdjustment field, which is only meaningful when dispatching to a 3PL.

destinationobject(DestinationForCreateWith3pl)required

Destination shape for POST /v1/movement-requests/create-with-3pl. Identical to DestinationForCreate plus the optional allowDeliveryDateAdjustment field, which is only meaningful when dispatching to a 3PL.

businessAreastring(BusinessArea)required

Enum:"Retail""Fleet"

Example:"Retail"

notesstring, <= 1024 characters

Any important notes relating to the movement request

Example:"Talk to Kevin for keys"

externalIdstring

Any external identifier you want to link with this movement request

Example:"some-external-identifier"

confirmedBystring, <= 128 characters

The person who confirmed the vehicle is on site and available for collection

Example:"John Doe"

requestedBystring, (email), <= 254 characters

Email of the person this movement is being raised for. Replaces the API key identity as the request's creator, so the tracking, delivered and aborted notifications are addressed to them rather than being dropped. Write only: the request stores it as its creator and does not return it.

Example:"john.doe@example.com"

moDelInformationobject

Key information for linking a Jigcar movement request to a MoDel job

transportMethodstring(TransportMethod)required

Enum:"DRIVEN""TRANSPORTED"

Example:"DRIVEN"

thirdPartyLogisticsProviderIdstringrequired

The id of the 3PL that should fulfil this movement

Example:"some-third-party-id"

curl -i -X POST \
  https://docs.jigcar.com/_mock/openapi-v1/movement-requests/create-with-3pl \
  -H 'Content-Type: application/json' \
  -H 'X-Jigcar-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "vehicle": {
      "vin": "string",
      "vrm": "string",
      "externalVehicleId": "STOCK-12345",
      "make": "Mercedes-Benz",
      "model": "A-Class",
      "modelVariant": "A 180 AMG Line Executive Hatchback"
    },
    "origin": {
      "location": {
        "type": "INTERNAL",
        "siteId": "some-site-id"
      },
      "readyToCollectFromTimeslot": "AM",
      "readyToCollectFromDate": "2023-10-29",
      "allowCollectionDateAdjustment": true
    },
    "destination": {
      "location": {
        "type": "INTERNAL",
        "siteId": "some-site-id"
      },
      "deliveryByTimeslot": "AM",
      "deliveryByDate": "2023-10-29",
      "deliveryByTime": "16:00",
      "deliverOnSpecifiedDate": true,
      "allowDeliveryDateAdjustment": true
    },
    "businessArea": "Retail",
    "notes": "Talk to Kevin for keys",
    "externalId": "some-external-identifier",
    "confirmedBy": "John Doe",
    "requestedBy": "john.doe@example.com",
    "moDelInformation": {
      "pin": "some-model-pin"
    },
    "transportMethod": "DRIVEN",
    "thirdPartyLogisticsProviderId": "some-third-party-id"
  }'

Responses

Created.

Bodyapplication/json

idstring, (ulid)required

The identifier for the vehicle movement request

Example:"01K4NNVBR6J323BY6X26J62WA5"

vehicleobject(Vehicle)required

originobject(OriginForCreate)required

The origin of the movement request.

Both readyToCollectFromDate and readyToCollectFromTimeslot are optional. Omitting them means "the vehicle is ready now": the date defaults to today at the origin site, and the timeslot to whichever slot that site's local clock is currently in. When the site's timezone cannot be resolved from its country code the timeslot falls back to ANYTIME, rather than bucketing against a clock we cannot place.

destinationobject(DestinationForCreate)required

The destination of the movement request.

Supply the deadline's time of day as deliveryByTime when you have one. It sets deliveryByTimeslot (before noon is AM, noon onwards is PM) and is also kept verbatim as the delivery hours, so a 16:00 deadline stays 16:00 rather than being widened to PM's 17:00 close.

An explicit deliveryByTimeslot always wins over deliveryByTime. When neither is given the timeslot is ANYTIME.

statusstring(VehicleMovementRequestStatus)required

The status of the movement request

Enum:"CREATED""SENT_TO_DRIVER""SENT_TO_3PL""SENT_TO_MARKETPLACE""SENT_TO_MULTIPLE_DRIVERS""ACCEPTED""ACCEPTED_SENT_TO_DRIVER""ACCEPTED_SENT_TO_3PL""ACCEPTED_SENT_TO_MARKETPLACE""PARTIALLY_PLANNED"

Example:"IN_PROGRESS"

completedOnstring, (datetime)(DateTime)

The date that the movement request was completed, if applicable

Example:"2025-07-01T09:00:00.000Z"

costobject(Money)

The cost of the movement, if known. Populated once the movement has been priced (e.g. by the assigned 3PL).

estimatedCostobject(Money)

What the movement is expected to cost, priced against the transport provider's rate card when the movement was created. Absent when the provider has no rate card for the requested transport method.

businessAreastring(BusinessArea)required

Enum:"Retail""Fleet"

Example:"Retail"

notesstring, <= 1024 characters

Any important notes relating to the movement request

Example:"Talk to Kevin for keys"

externalIdstring

Any external identifier you want to link with this movement request

Example:"some-external-identifier"

confirmedBystring, <= 128 characters

The person who confirmed the vehicle is on site and available for collection

Example:"John Doe"

moDelInformationobject

Key information for linking a Jigcar movement request to a MoDel job

transportMethodstring(TransportMethod)required

Enum:"DRIVEN""TRANSPORTED"

Example:"DRIVEN"

providerDriverProvider (object) or ThirdPartyLogisticsProvider (object) or MarketplaceProvider (object)

One of:

trackingUrlstring, (uri)

Public tracking page for this movement. Present once the movement has a tracking record — immediately for movements created into the planning pool, and after the transport provider has accepted otherwise. Omitted when tracking is disabled for your organisation.

Example:"https://tracking.jigcar.com?trackingId=3f1c9a7e-2b6d-4d2a-9c1e-8e2b1d5a6f00&vinOrVrm=AB12CDE"

Response

{
  "id": "01K4NNVBR6J323BY6X26J62WA5",
  "vehicle": {
    "vin": "string",
    "vrm": "string",
    "externalVehicleId": "STOCK-12345",
    "make": "Mercedes-Benz",
    "model": "A-Class",
    "modelVariant": "A 180 AMG Line Executive Hatchback"
  },
  "origin": {
    "location": { … },
    "readyToCollectFromTimeslot": "AM",
    "readyToCollectFromDate": "2023-10-29",
    "estimatedCollectionTimeslot": "AM",
    "estimatedCollectionDate": "2023-10-29"
  },
  "destination": {
    "location": { … },
    "deliveryByTimeslot": "AM",
    "deliveryByDate": "2023-10-29",
    "deliveryByTime": "16:00",
    "deliverOnSpecifiedDate": true,
    "estimatedDeliveryTimeslot": "AM",
    "estimatedDeliveryDate": "2023-10-29"
  },
  "status": "IN_PROGRESS",
  "completedOn": "2025-07-01T09:00:00.000Z",
  "cost": {
    "centAmount": 12500,
    "currencyCode": "GBP"
  },
  "estimatedCost": {
    "centAmount": 12500,
    "currencyCode": "GBP"
  },
  "businessArea": "Retail",
  "notes": "Talk to Kevin for keys",
  "externalId": "some-external-identifier",
  "confirmedBy": "John Doe",
  "moDelInformation": {
    "pin": "some-model-pin"
  },
  "transportMethod": "DRIVEN",
  "provider": {
    "type": "DRIVER",
    "id": "some-driver-id",
    "firstname": "John",
    "surname": "Wick"
  },
  "trackingUrl": "https://tracking.jigcar.com?trackingId=3f1c9a7e-2b6d-4d2a-9c1e-8e2b1d5a6f00&vinOrVrm=AB12CDE"
}