create Trip

Creates a trip (travel request) for an employee in Dice, including its itinerary, budget and – optionally – the approvals already taken in your system.

Request Parameters

Param	Required	Description
tripId	Mandatory	Your unique trip reference (e.g. the trip number in your system). Use it for all later calls. Must be unique per employee. If the same `tripId` already exists for another employee in your company, Dice stores it as `<tripId>_<id>` and returns that value – always store the `tripId` returned in the response.
tripStatus	Mandatory	Status the trip should be created in (case-insensitive). Values: `PENDING`, `APPROVAL`, `COMPLETED`.
employeeCode	Conditional	Employee code of the traveller. One of `employeeCode`, `employeeEmail` or `employeeData` is mandatory; the code wins if both code and email are sent.
employeeEmail	Conditional	Email of the traveller. Used when `employeeCode` is not sent.
tripStartDate	Mandatory	Trip start, epoch milliseconds. Must equal `data.origin.dateTime`.
tripEndDate	Mandatory	Trip end, epoch milliseconds. Must equal `data.return.dateTime`, or the last city `endTime` when `data.endTripHere` is `true`.
data	Mandatory	Trip itinerary and budget details. Mandatory.
data.title	Optional	Trip title shown to employees and approvers. Recommended.
data.origin	Mandatory	Start of the trip. Mandatory.
data.origin.cityName	Mandatory	Name of the city the trip starts from. Must match a city in the Dice city master (e.g. `Mumbai`, `New Delhi`).
data.origin.dateTime	Mandatory	Trip start date & time (departure from origin). Back-dated trips are rejected unless allowed for your account. If `tripStartDate` is also sent, both must be identical. Epoch time in milliseconds (UTC).
data.origin.departureTime	Optional	Departure time from origin, if different from `dateTime`. Epoch time in milliseconds (UTC).
data.origin.journeyHours	Optional	Travel duration in hours for the first leg.
data.origin.stayHours	Optional	Hours spent at origin before departure.
data.origin.coords	Optional	Geo coordinates of a location.
data.origin.coords.name	Optional	Display name of the location.
data.origin.coords.lat	Optional	Latitude.
data.origin.coords.lng	Optional	Longitude.
data.cities[]	Mandatory	Destination cities in visiting order. Mandatory – send at least one city.
data.cities[].cityName	Mandatory	Destination city name. Must match a city in the Dice city master.
data.cities[].startTime	Optional	Arrival / start of stay in this city. Epoch time in milliseconds (UTC).
data.cities[].endTime	Optional	Departure / end of stay in this city. Must not be before the previous city’s end. Epoch time in milliseconds (UTC).
data.cities[].days	Optional	Number of days in this city. Required when `endTime` is not sent (end is then computed as start + days).
data.cities[].travel	Mandatory	How the traveller reaches this city. Mandatory (`travel.type`).
data.cities[].travel.type	Mandatory	Mode of travel to this city. Case-insensitive. If the city is the same as the previous city, travel is automatically set to `none`. Mandatory on Create Trip for every city and for `return`. Values: `flight`, `train`, `bus`, `cab`, `own`, `none`.
data.cities[].travel.amount	Optional	Estimated / quoted fare for this leg in the employee’s currency. Used for `flight` only; for other modes Dice computes the budget from the travel policy. If omitted for a flight, Dice uses its policy-based estimate. A configured flight buffer may be added on top.
data.cities[].travel.title	Optional	Short label for the selected option, e.g. airline + flight number.
data.cities[].travel.selected	Optional	Your reference / key for the selected fare or train option.
data.cities[].travel.returnSelected	Optional	Reference / key of the return fare when a round-trip fare was selected.
data.cities[].travel.travelBookingType	Optional	Who books this leg, e.g. `SELF` or `ADMIN`. Informational.
data.cities[].travel.travelJourneyType	Optional	Flight journey type. Defaults to `ONE_WAY`. Values: `ONE_WAY`, `ROUND_TRIP`.
data.cities[].travel.travellers[]	Optional	Travellers on this flight leg (flights only).
data.cities[].travel.travellers[].code	Optional	Employee code of the traveller (if the traveller is an employee).
data.cities[].travel.travellers[].name	Optional	Full name.
data.cities[].travel.travellers[].firstName	Optional	First name.
data.cities[].travel.travellers[].lastName	Optional	Last name.
data.cities[].travel.travellers[].email	Optional	Email address.
data.cities[].travel.travellers[].mobile	Optional	Mobile number with country code.
data.cities[].travel.travellers[].gender	Optional	Gender. Values: `MALE`, `FEMALE`.
data.cities[].travel.travellers[].paxType	Optional	Passenger type (used for flight fare split). Values: `ADULT`, `CHILD`, `INFANT`.
data.cities[].travel.travellers[].userType	Optional	Free text traveller type, e.g. `EMPLOYEE` or `GUEST`.
data.cities[].travel.travellers[].dob	Optional	Date of birth. Epoch time in milliseconds (UTC).
data.cities[].travel.travellers[].primary	Optional	`true` for the lead traveller.
data.cities[].stay	Mandatory	Accommodation in this city. Mandatory (`stay.type`, use `none` if not needed).
data.cities[].stay.type	Mandatory	Stay type. Use `none` when no accommodation is needed. Mandatory on Create Trip for every city. Values: `hotel`, `Guest House`, `none`.
data.cities[].stay.amount	Optional	Total stay cost for the whole stay in this city. If omitted, Dice uses policy-based hotel price x nights. A configured hotel buffer may be added on top.
data.cities[].stay.pricePerNight	Optional	Price per night. When sent (> 0) it overrides `amount` as `pricePerNight x number of nights`.
data.cities[].stay.name	Optional	Hotel name.
data.cities[].stay.hotelType	Optional	Hotel category / star rating as text.
data.cities[].stay.code	Optional	Your hotel code.
data.cities[].stay.roomKey	Optional	Your room / rate code.
data.cities[].stay.hotelId	Optional	Your hotel identifier (hotel only, not Guest House).
data.cities[].stay.propertyType	Optional	Property type, e.g. `Hotel`, `Serviced Apartment`.
data.cities[].stay.checkInDate	Optional	Planned check-in. Epoch time in milliseconds (UTC).
data.cities[].stay.checkOutDate	Optional	Planned check-out. Epoch time in milliseconds (UTC).
data.cities[].stay.travellers[]	Optional	Guests staying in this hotel.
data.cities[].stay.travellers[].code	Optional	Employee code of the traveller (if the traveller is an employee).
data.cities[].stay.travellers[].name	Optional	Full name.
data.cities[].stay.travellers[].firstName	Optional	First name.
data.cities[].stay.travellers[].lastName	Optional	Last name.
data.cities[].stay.travellers[].email	Optional	Email address.
data.cities[].stay.travellers[].mobile	Optional	Mobile number with country code.
data.cities[].stay.travellers[].gender	Optional	Gender. Values: `MALE`, `FEMALE`.
data.cities[].stay.travellers[].paxType	Optional	Passenger type (used for flight fare split). Values: `ADULT`, `CHILD`, `INFANT`.
data.cities[].stay.travellers[].userType	Optional	Free text traveller type, e.g. `EMPLOYEE` or `GUEST`.
data.cities[].stay.travellers[].dob	Optional	Date of birth. Epoch time in milliseconds (UTC).
data.cities[].stay.travellers[].primary	Optional	`true` for the lead traveller.
data.cities[].arrivalTime	Optional	Actual arrival time in this city. Epoch time in milliseconds (UTC).
data.cities[].departureTime	Optional	Actual departure time from this city. Epoch time in milliseconds (UTC).
data.cities[].journeyHours	Optional	Travel duration in hours to reach this city.
data.cities[].stayHours	Optional	Hours spent in this city.
data.cities[].roundTrip	Optional	Set `true` when this leg is the return part of a round-trip booked with the previous leg.
data.cities[].coords	Optional	Geo coordinates of a location.
data.cities[].coords.name	Optional	Display name of the location.
data.cities[].coords.lat	Optional	Latitude.
data.cities[].coords.lng	Optional	Longitude.
data.cities[].lat	Optional	Latitude of the preferred stay area (hotel / Guest House only).
data.cities[].lng	Optional	Longitude of the preferred stay area (hotel / Guest House only).
data.cities[].locationId	Optional	Your locality / area id for the stay (hotel / Guest House only).
data.cities[].flightForms	Optional	Custom flight form fields configured for your account (key = field name). Used when `travel.type` = `flight`.
data.cities[].hotelForms	Optional	Custom hotel form fields configured for your account. Used when `stay.type` = `hotel`.
data.cities[].trainForms	Optional	Custom train form fields configured for your account. Used when `travel.type` = `train`.
data.cities[].flightJustificationRemarks	Optional	Justification when the selected flight is not the cheapest / is out of policy.
data.cities[].hotelJustificationRemarks	Optional	Justification when the selected hotel is out of policy.
data.return	Conditional	Return leg to the origin city. Send it when the trip returns to the origin; the trip is then closed. If not sent, `data.endTripHere` must be `true`.
data.return.cityName	Mandatory	Return city name. Must be the same as `origin.cityName`.
data.return.dateTime	Mandatory	Date & time of arrival back at origin. Becomes the trip end date. Must not be before the last city’s end. If `tripEndDate` is sent, both must be identical. Epoch time in milliseconds (UTC).
data.return.travel	Mandatory	How the traveller returns. Mandatory (`travel.type`).
data.return.travel.type	Mandatory	Mode of travel to this city. Case-insensitive. If the city is the same as the previous city, travel is automatically set to `none`. Mandatory on Create Trip for every city and for `return`. Values: `flight`, `train`, `bus`, `cab`, `own`, `none`.
data.return.travel.amount	Optional	Estimated / quoted fare for this leg in the employee’s currency. Used for `flight` only; for other modes Dice computes the budget from the travel policy. If omitted for a flight, Dice uses its policy-based estimate. A configured flight buffer may be added on top.
data.return.travel.title	Optional	Short label for the selected option, e.g. airline + flight number.
data.return.travel.selected	Optional	Your reference / key for the selected fare or train option.
data.return.travel.returnSelected	Optional	Reference / key of the return fare when a round-trip fare was selected.
data.return.travel.travelBookingType	Optional	Who books this leg, e.g. `SELF` or `ADMIN`. Informational.
data.return.travel.travelJourneyType	Optional	Flight journey type. Defaults to `ONE_WAY`. Values: `ONE_WAY`, `ROUND_TRIP`.
data.return.travel.travellers[]	Optional	Travellers on this flight leg (flights only).
data.return.travel.travellers[].code	Optional	Employee code of the traveller (if the traveller is an employee).
data.return.travel.travellers[].name	Optional	Full name.
data.return.travel.travellers[].firstName	Optional	First name.
data.return.travel.travellers[].lastName	Optional	Last name.
data.return.travel.travellers[].email	Optional	Email address.
data.return.travel.travellers[].mobile	Optional	Mobile number with country code.
data.return.travel.travellers[].gender	Optional	Gender. Values: `MALE`, `FEMALE`.
data.return.travel.travellers[].paxType	Optional	Passenger type (used for flight fare split). Values: `ADULT`, `CHILD`, `INFANT`.
data.return.travel.travellers[].userType	Optional	Free text traveller type, e.g. `EMPLOYEE` or `GUEST`.
data.return.travel.travellers[].dob	Optional	Date of birth. Epoch time in milliseconds (UTC).
data.return.travel.travellers[].primary	Optional	`true` for the lead traveller.
data.return.arrivalTime	Optional	Arrival time at origin. Epoch time in milliseconds (UTC).
data.return.journeyHours	Optional	Travel duration in hours.
data.return.stayHours	Optional	Hours of stay after return (normally 0).
data.return.roundTrip	Optional	`true` when the return is part of a round-trip fare.
data.return.coords	Optional	Geo coordinates of a location.
data.return.coords.name	Optional	Display name of the location.
data.return.coords.lat	Optional	Latitude.
data.return.coords.lng	Optional	Longitude.
data.return.flightJustificationRemarks	Optional	Justification for an out-of-policy return flight.
data.allowance	Mandatory	Cash advance / allowance requested for the trip in the employee’s currency. It is added to the trip budget. Always send this field – use `0` when no allowance is needed.
data.additionalAmount	Optional	Any additional amount to be added to the trip budget (e.g. visa, local conveyance).
data.advance	Optional	`true` if `allowance` should be issued as a cash advance / petty cash.
data.qrCard	Optional	`true` if `allowance` should be loaded to a QR card instead of an advance. Ignored when `advance` is `true`.
data.qrCardType	Optional	QR card type. Required when `qrCard` is `true` and QR card types are enabled for your account.
data.foreignCurrency	Optional	Currency code for forex cards (international trips, only when forex cards are enabled).
data.exchangeRate	Optional	Exchange rate to use with `foreignCurrency`.
data.automation	Optional	`true` to let Dice auto-book the trip services after approval (when auto booking is enabled for your account).
data.admin	Optional	`true` if the trip will be booked by the travel desk / admin. `false` (default) uses your account’s self-booking setting.
data.draft	Optional	`true` to save the trip as a draft (no approval is triggered).
data.endTripHere	Conditional	Must be `true` when `data.return` is not sent and the trip ends at the last city. If neither `data.return` nor `endTripHere = true` is sent, the trip is created as an open trip (not fully created) and blocks the employee’s next trip.
data.skipApproval	Conditional	Must be `true` when the trip does not need approval in Dice; the trip is approved immediately and `approvers` are ignored. If not sent or `false`, the Dice approval flow is triggered.
data.skipApprovalRemarks	Optional	Reason for skipping approval. Stored with the trip; used only when `skipApproval` is `true`.
data.forms	Optional	Custom trip form fields configured for your account (key = field name as configured in Dice, value = answer).
data.remarks	Optional	Remarks per component. Keys are component names such as `flight`, `hotel`, `train`, `cab`.
approvers	Optional	Approvals already taken in your system. Optional – when omitted, Dice runs your configured approval workflow.
approvers.tripApprovers[]	Optional	Approvers of this trip. Each approver gets the next approval level.
approvers.tripApprovers[].code	Optional	Approver’s employee code. Must be unique in your company.
approvers.tripApprovers[].name	Optional	Approver’s full name.
approvers.tripApprovers[].email	Optional	Approver’s email.
approvers.tripApprovers[].status	Optional	Approval status of this approver. Case-insensitive. When all approvers are `Approved`, the trip is marked approved immediately; otherwise it waits for the pending approvers in Dice. Values: `Pending`, `Approved`, `Declined`, `AutoApproved`, `Completed`, `Cancelled`, `Reverted`, `Hold`, `UnHold`.
approvers.tripApprovers[].approvalTimestamp	Optional	When the approver acted (or was assigned, if pending). Epoch time in milliseconds (UTC).
employeeData	Conditional	Traveller details, used to create the employee when neither `employeeCode` nor `employeeEmail` is sent.
employeeData.code	Mandatory	Employee code to create.
employeeData.firstName	Mandatory	First name.
employeeData.lastName	Mandatory	Last name.
employeeData.email	Mandatory	Work email.
employeeData.office	Mandatory	Office / branch name. Created automatically if it does not exist.
employeeData.department	Mandatory	Department name within the office. Created automatically if it does not exist.
employeeData.mobile	Optional	Mobile number.
employeeData.gender	Optional	Gender. Values: `MALE`, `FEMALE`.
employeeData.grade	Optional	Employee grade / band (drives travel policy). Created if it does not exist.
employeeData.hierarchy	Optional	Parent office / region name, when your account uses office hierarchy.
employeeData.manager	Optional	Reporting manager’s employee code (UPPERCASE).
employeeData.alternate	Optional	Alternate approver’s employee code (UPPERCASE).
employeeData.hrHead	Optional	HR head’s employee code (UPPERCASE).
employeeData.customFields	Optional	Custom employee fields configured for your account.
employeeData.bankAccount	Optional	Reimbursement bank account (both fields required if sent).
employeeData.bankAccount.accountNo	Optional	Bank account number.
employeeData.bankAccount.ifsc	Optional	IFSC code.

Request

Create Trip request body.

tripIdstringRequired

Your unique trip reference (e.g. the trip number in your system). Use it for all later calls. Must be unique per employee. If the same tripId already exists for another employee in your company, Dice stores it as <tripId>_<id> and returns that value – always store the tripId returned in the response.

tripStatusenumRequired

Status the trip should be created in (case-insensitive):

PENDING – trip is approved and active (ready for booking / travel). If the trip is already approved in your system, send PENDING.
APPROVAL – trip is in the approval state, waiting for approvers.
COMPLETED – travel is completed.

Allowed values:

tripStartDatelongRequired

Trip start. Must equal data.origin.dateTime. Epoch time in milliseconds (UTC).

tripEndDatelongRequired

Trip end. Must equal data.return.dateTime (or the last city’s endTime when there is no return) and must not be before tripStartDate. Epoch time in milliseconds (UTC).

dataobjectRequired

Trip itinerary and budget details. Mandatory.

employeeCodestringOptional

Employee code of the traveller (trip owner) in Dice. One of employeeCode, employeeEmail or employeeData is mandatory. If both code and email are sent, the code is used.

employeeEmailstringOptionalformat: "email"

Email of the traveller in Dice. Used when employeeCode is not sent.

approversobjectOptional

Approvals already taken in your system. Optional – when omitted, Dice runs your configured approval workflow.

employeeDataobjectOptional

Employee details for auto-creation when the employee does not exist yet. Optional (see availability note).

Response

tripIdstring

Trip reference stored in Dice. May differ from the request (<tripId>_<id>) – store this value.

successboolean

true when the operation succeeded.

messagestring

Outcome message.

Create Trip

Request Parameters

Headers

Request

Response