Skip to content

Create vehicle movement request

Request

Creates a movement request for the provided vehicle and sends it to an internal planning pool

Security
JigcarAPIAuth
Bodyapplication/jsonrequired
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.

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"
curl -i -X POST \
  https://docs.jigcar.com/_mock/openapi-v1/movement-requests/create-in-planning-pool \
  -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"
    },
    "destination": {
      "location": {
        "type": "INTERNAL",
        "siteId": "some-site-id"
      },
      "deliveryByTimeslot": "AM",
      "deliveryByDate": "2023-10-29",
      "deliveryByTime": "16:00",
      "deliverOnSpecifiedDate": 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"
  }'

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"
}