Skip to content
API reference
/
Trip
/
/
Create trip

Trip API (v2)

Download OpenAPI description
TripApi.json
TripApi.yaml
Languages
Servers
Sandbox URL
https://api-ext-sboxmeta.partners.spotnana.com
Spotnana mock server
https://developer.spotnana.com/_mock/openapi/tripapi

Trips

APIs to manage trips.

Operations

Create trip

Request

This endpoint creates a trip object. A trip is a container object for all related PNRs associated with a trip.

Security
Bearer
Bodyapplication/json
tripNamestringrequired

Name of the trip.

tripDescriptionstring

Description of the trip.

userIdobject(UserId)

User identifier

registrarIdobject(UserId)

Creator of the Trip.

curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v2/trips \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tripName": "string",
    "tripDescription": "string",
    "userId": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    },
    "registrarId": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  }'

Responses

Created

Bodyapplication/json
idstring
Example: 1234567890
Response
application/json
{
  "id": "string"
}

Update trip

Request

This endpoint updates trip by ID.

Security
Bearer
Path
tripIdstringrequired

Identifier for trip.

Example: 2398199412
Bodyapplication/json
tripIdstringrequired

Spotnana trip Id

Example: "6926658168"
tripNamestringrequired

Name of the trip

Example: "JFK SFO Trip"
tripDescriptionstring

Trip description

Example: "JFK SFO Business Trip"
curl -i -X PUT \
  https://api-ext-sboxmeta.partners.spotnana.com/v2/trips/2398199412 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tripId": "6926658168",
    "tripName": "JFK SFO Trip",
    "tripDescription": "JFK SFO Business Trip"
  }'

Responses

Updated Successfully

Response
No content

Get trip details

Request

This endpoint gets trip details for a given trip ID.

Note: For air bookings made via Travelfusion (i.e., pnrs.data.sourceInfo.bookingSource: TRAVEL_FUSION) the refundPolicy and exchangePolicy fields will be empty.

Security
Bearer
Path
tripIdstringrequired

Trip ID

Example: 6926658168
Query
refreshTypestring(RefreshType)

Refresh Type

Enum"REFRESH_TYPE_BLOCKING""REFRESH_TYPE_ASYNC""REFRESH_TYPE_DISABLED"
Example: refreshType=REFRESH_TYPE_BLOCKING
fetchMappedDataboolean

If true, fetch PNRs from already mapped data present in DB

Default false
curl -i -X GET \
  'https://api-ext-sboxmeta.partners.spotnana.com/v3/trips/6926658168/detail?refreshType=REFRESH_TYPE_BLOCKING&fetchMappedData=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
basicTripInfoobject(BasicTripInfo)required

Basic trip info

basicTripInfo.​tripIdstringrequired

Spotnana trip Id

Example: "6926658168"
basicTripInfo.​tripNamestringrequired

Name of the trip

Example: "JFK SFO Trip"
basicTripInfo.​tripDescriptionstring

Trip description

Example: "JFK SFO Business Trip"
basicTripInfo.​applicationIdstring(uuid)

Application id used for the trip.

basicTripInfo.​startDateobject(DateModel)

Date in ISO 8601 standard.

basicTripInfo.​endDateobject(DateModel)

Date in ISO 8601 standard.

basicTripInfo.​userIdobject(UserId)

The user Id of the traveler to whom the trip belongs to.

basicTripInfo.​registrarUserIdobject(UserId)

The user Id of the registrar of the adhoc traveler.

basicTripInfo.​tripMetadataobject(TripMetadata)

Metadata for the trip

basicTripInfo.​tripDisabledInfoobject(TripDisabledInfo)

Information regarding whether the trip is disabled and if so, the reason why.

basicTripInfo.​stealthModeobject(StealthMode)

Stealth mode configuration with type and label.

basicTripInfo.​stealthTypestring(StealthType)Deprecated

Stealth type.

Enum"STEALTH_TYPE_1""STEALTH_TYPE_2""STEALTH_TYPE_3"
pnrsArray of objects(PnrDetailsResponseWithId)required
pnrs[].​pnrIdstring

Unique PNR ID

Example: "6926658168"
pnrs[].​dataobject(PnrData)

Pnr data with all information about a single booking containing one of Air, Hotel, Car, Rail, Limo or Miscellaneous PNR.

pendingShellPnrsArray of objects(PnrDetailsResponseWithId)
pendingManualFormPnrsArray of objects(PnrDetailsResponseWithId)
tripBookingStatusstring(UserFacingStatus)

User facing booking status

Enum"UNKNOWN_STATUS""PENDING_STATUS""CONFIRMED_STATUS""ACTIVE_STATUS""COMPLETED_STATUS""CANCELLED_STATUS""REFUNDED_STATUS""VOIDED_STATUS""PROCESSING_STATUS""UNCONFIRMED_STATUS"
eventSummaryobject(TravelerEventSummary)

Event summary for a traveler

simplePnrsArray of objects(SimplePnr)
additionalInfoobject(TripAdditionalInfo)

Additional information about the trip

tripPaymentInfoobject(TripPaymentInfo)

Payment info for a given trip. Fares of pending manual form and pending shell pnrs are not considered.

tripStatusstring(PnrBookingStatus)Deprecated

User facing status for this booking

Enum"PENDING""CONFIRMED""ACTIVE""COMPLETED""CANCELLED""REFUNDED""VOIDED""PROCESSING""UNCONFIRMED""AIRLINE_CONTROL"
Response
application/json
{
  "basicTripInfo": {
    "tripId": "6926658168",
    "tripName": "JFK SFO Trip",
    "tripDescription": "JFK SFO Business Trip",
    "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
    "startDate": { … },
    "endDate": { … },
    "userId": { … },
    "registrarUserId": { … },
    "tripMetadata": { … },
    "tripDisabledInfo": { … },
    "stealthType": "STEALTH_TYPE_1",
    "stealthMode": { … }
  },
  "pnrs": [
    { … }
  ],
  "pendingShellPnrs": [
    { … }
  ],
  "pendingManualFormPnrs": [
    { … }
  ],
  "tripStatus": "CONFIRMED",
  "tripBookingStatus": "PENDING_STATUS",
  "eventSummary": {
    "id": "12345",
    "type": "GENERIC",
    "name": "My event",
    "description": "This is an event description",
    "startDateTime": { … },
    "endDateTime": { … },
    "location": { … },
    "contacts": [ … ],
    "documents": [ … ],
    "bookingGuidelines": [ … ],
    "allowedBookingTypes": [ … ],
    "eventUserRsvp": { … },
    "contactInfoList": [ … ],
    "companyId": { … },
    "runningStatus": "UPCOMING",
    "status": "DRAFT",
    "isRemovedParticipant": true,
    "inviteEmailConfig": { … }
  },
  "simplePnrs": [
    { … }
  ],
  "additionalInfo": {
    "vpayBillBack": "B"
  },
  "tripPaymentInfo": {
    "totalFare": { … },
    "totalFareAmount": { … },
    "serviceFeeFareAmount": { … }
  }
}

Delete trip

Request

This endpoint deletes a trip by ID.

Security
Bearer
Path
tripIdstringrequired

Trip ID

Example: 6926658168
Bodyapplication/json
allowEmptyTripDeletionOnlyboolean

If true, only allows deletion of empty trips (trips with no PNRs). If false (default), allows deletion regardless of PNRs.

Default false
curl -i -X DELETE \
  https://api-ext-sboxmeta.partners.spotnana.com/v3/trips/6926658168 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "allowEmptyTripDeletionOnly": false
  }'

Responses

Deleted Successfully

Response
No content

Update trip details for trip Id

Request

Security
Bearer
Path
tripIdstringrequired

Trip ID

Example: 6926658168
Bodyapplication/json
tripContactsArray of objects(TripContact)
tripCommunicationPreferencesobject(TripCommunicationPreferences)

Communication preferences for the trip

curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v3/trips/6926658168 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tripContacts": [
      {
        "label": "Coordinator",
        "name": "Himani Jain",
        "email": "himani@spotnana.com",
        "phoneNumber": {
          "countryCode": 91,
          "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
          "extension": "222",
          "isoCountryCode": "IN",
          "italianLeadingZero": true,
          "nationalNumber": 8150,
          "numberOfLeadingZeros": 1,
          "preferredDomesticCarrierCode": "7",
          "rawInput": "77777",
          "type": "MOBILE"
        },
        "isPrimary": true,
        "restrictVisibility": true
      }
    ],
    "tripCommunicationPreferences": {
      "tripEmailPreferences": {
        "bucketEmailPreferences": {
          "bucketTypes": [
            "BOOKING_CONFIRMATIONS"
          ],
          "isEnabled": false,
          "toEmails": [
            "example@email.com"
          ],
          "ccEmails": [
            "example@email.com"
          ],
          "bccEmails": [
            "example@email.com"
          ]
        }
      }
    }
  }'

Responses

OK

Response
No content

List trip summaries for a user

Request

Retrieves the list of trip summaries associated with a user.

Security
Bearer
Path
userIdstring(uuid)required

Identifier for the user whose trip summaries are requested.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Bodyapplication/jsonrequired
paginationRequestParamsobject(OffsetBasedPaginationRequestParams)required

Pagination parameters for requests.

paginationRequestParams.​offsetinteger(int32)>= 0

The starting index in the list from which results are returned. The value must be greater than or equal to 0.

Default 0
paginationRequestParams.​limitinteger(int32)>= 1

Maximum number of results to be fetched.

Default 100
includePnrSummariesboolean

Boolean flag to include PNR summaries in the response

Example: true
tripFiltersArray of objects(TripFilters)

Filter for the list trip summary request.

sortOptionsArray of objects(TripSortOptions)

Sort options for the list trip summary request

curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v3/trips/users/4974a66b-7493-4f41-908c-58ba81093947/list \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "paginationRequestParams": {
      "offset": 0,
      "limit": 100
    },
    "includePnrSummaries": true,
    "tripFilters": [
      {
        "filterType": "string",
        "userIds": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ]
      }
    ],
    "sortOptions": [
      {
        "sortField": "START_DATE",
        "sortOrder": "DESC"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
paginationResponseParamsobject(OffsetBasedPaginationResponseParams)required

Pagination parameters for response.

paginationResponseParams.​totalNumResultsinteger(int32)required

Total number of results.

tripSummariesArray of objects(TripSummary)

List of Trip summaries

failedTripSummariesArray of objects(TripSummary)

List of Trip summaries

Response
application/json
{
  "paginationResponseParams": {
    "totalNumResults": 0
  },
  "tripSummaries": [
    { … }
  ],
  "failedTripSummaries": [
    { … }
  ]
}

List trip summaries for a company

Request

Retrieves the list of trip summaries associated with a company.

Security
Bearer
Path
companyIdstring(uuid)required

Identifier for the company whose trip summaries are requested.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Bodyapplication/jsonrequired
paginationRequestParamsobject(OffsetBasedPaginationRequestParams)required

Pagination parameters for requests.

paginationRequestParams.​offsetinteger(int32)>= 0

The starting index in the list from which results are returned. The value must be greater than or equal to 0.

Default 0
paginationRequestParams.​limitinteger(int32)>= 1

Maximum number of results to be fetched.

Default 100
includePnrSummariesboolean

Boolean flag to include PNR summaries in the response

Example: true
tripFiltersArray of objects(TripFilters)

Filter for the list trip summary request.

sortOptionsArray of objects(TripSortOptions)

Sort options for the list trip summary request

curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v3/trips/companies/4974a66b-7493-4f41-908c-58ba81093947/list \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "paginationRequestParams": {
      "offset": 0,
      "limit": 100
    },
    "includePnrSummaries": true,
    "tripFilters": [
      {
        "filterType": "string",
        "userIds": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ]
      }
    ],
    "sortOptions": [
      {
        "sortField": "START_DATE",
        "sortOrder": "DESC"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
paginationResponseParamsobject(OffsetBasedPaginationResponseParams)required

Pagination parameters for response.

paginationResponseParams.​totalNumResultsinteger(int32)required

Total number of results.

tripSummariesArray of objects(TripSummary)

List of Trip summaries

failedTripSummariesArray of objects(TripSummary)

List of Trip summaries

Response
application/json
{
  "paginationResponseParams": {
    "totalNumResults": 0
  },
  "tripSummaries": [
    { … }
  ],
  "failedTripSummaries": [
    { … }
  ]
}

List trip summaries for travelers managed by an arranger

Request

Retrieves the list of trip summaries for all travelers managed by a specific arranger. This endpoint can be used for arrangers whose role types are COMPANY_TRAVEL_ARRANGER or TRAVEL_ARRANGER.

Security
Bearer
Path
arrangerIdstring(uuid)required

Identifier for the arranger whose managed travelers trip summaries are requested.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Bodyapplication/jsonrequired
paginationRequestParamsobject(OffsetBasedPaginationRequestParams)required

Pagination parameters for requests.

paginationRequestParams.​offsetinteger(int32)>= 0

The starting index in the list from which results are returned. The value must be greater than or equal to 0.

Default 0
paginationRequestParams.​limitinteger(int32)>= 1

Maximum number of results to be fetched.

Default 100
includePnrSummariesboolean

Boolean flag to include PNR summaries in the response

Example: true
tripFiltersArray of objects(TripFilters)

Filter for the list trip summary request.

sortOptionsArray of objects(TripSortOptions)

Sort options for the list trip summary request

curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v3/trips/arrangers/4974a66b-7493-4f41-908c-58ba81093947/list \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "paginationRequestParams": {
      "offset": 0,
      "limit": 100
    },
    "includePnrSummaries": true,
    "tripFilters": [
      {
        "filterType": "string",
        "userIds": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ]
      }
    ],
    "sortOptions": [
      {
        "sortField": "START_DATE",
        "sortOrder": "DESC"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
paginationResponseParamsobject(OffsetBasedPaginationResponseParams)required

Pagination parameters for response.

paginationResponseParams.​totalNumResultsinteger(int32)required

Total number of results.

tripSummariesArray of objects(TripSummary)

List of Trip summaries

failedTripSummariesArray of objects(TripSummary)

List of Trip summaries

Response
application/json
{
  "paginationResponseParams": {
    "totalNumResults": 0
  },
  "tripSummaries": [
    { … }
  ],
  "failedTripSummaries": [
    { … }
  ]
}

Get trip partner info

Request

This endpoint provides info related to partner for the trip.

Security
Bearer
Path
tripIdstringrequired

Identifier for trip.

Example: 2398199412
bookerEmailIdstringrequired

Booker Email Id for whom budget info will be fetched.

Example: akanksha@spotnana.com
Query
revealReasonstring

Reason for revealing the budget card information.

Example: revealReason=Purchase a Flight
curl -i -X GET \
  'https://api-ext-sboxmeta.partners.spotnana.com/v2/trips/2398199412/booker-email/akanksha@spotnana.com/partner-info?revealReason=Purchase+a+Flight' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
tripIdstringrequired

Spotnana trip Id

Example: "6926658168"
partnerInfoobject(TripPartnerInfo)required

Partner info such as budget info for a given trip Id.

partnerInfo.​partnerInfoTypestring(TripPartnerInfoType)required

Trip Partner Info type.

Value"BUDGET"
partnerInfo.​partnerInfoDetailsTripBudgetInfoWrapper (object)(TripPartnerInfoDetails)required
One of:

OneOf trip partner info Details

partnerInfo.​partnerInfoDetails.​tripBudgetInfoobject(TripBudgetInfo)

Trip budget Info

Response
application/json
{
  "tripId": "6926658168",
  "partnerInfo": {
    "partnerInfoType": "BUDGET",
    "partnerInfoDetails": { … }
  }
}

Get tripDeprecated

Request

Retrieves trip info by ID.

Deprecation notice

The Get Trip /v2/trips/{tripId} endpoint has been deprecated. Use the new Get trip details /v3/trips/{tripId}/detail endpoint instead.

Security
Bearer
Path
tripIdstringrequired

Identifier for trip.

Example: 2398199412
curl -i -X GET \
  https://api-ext-sboxmeta.partners.spotnana.com/v2/trips/2398199412 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
tripIdstringrequired

Spotnana trip Id

Example: "6926658168"
tripNamestringrequired

Name of the trip

Example: "JFK SFO Trip"
tripDescriptionstring

Trip description

Example: "JFK SFO Business Trip"
applicationIdstring(uuid)

Application id used for the trip.

startDateobject(DateModel)

Date in ISO 8601 standard.

endDateobject(DateModel)

Date in ISO 8601 standard.

userIdobject(UserId)

The user Id of the traveler to whom the trip belongs to.

registrarUserIdobject(UserId)

The user Id of the registrar of the adhoc traveler.

tripMetadataobject(TripMetadata)

Metadata for the trip

tripDisabledInfoobject(TripDisabledInfo)

Information regarding whether the trip is disabled and if so, the reason why.

stealthModeobject(StealthMode)

Stealth mode configuration with type and label.

stealthTypestring(StealthType)Deprecated

Stealth type.

Enum"STEALTH_TYPE_1""STEALTH_TYPE_2""STEALTH_TYPE_3"
Response
application/json
{
  "tripId": "6926658168",
  "tripName": "JFK SFO Trip",
  "tripDescription": "JFK SFO Business Trip",
  "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
  "startDate": {
    "iso8601": "2017-07-21"
  },
  "endDate": {
    "iso8601": "2017-07-21"
  },
  "userId": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "registrarUserId": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "tripMetadata": {
    "hasTripOverride": true,
    "preferredCurrency": "USD",
    "tripContacts": [ … ],
    "tripCommunicationPreferences": { … }
  },
  "tripDisabledInfo": {
    "disabledReason": "MAX_BOOKINGS_EXCEEDED",
    "isDisabled": false
  },
  "stealthType": "STEALTH_TYPE_1",
  "stealthMode": {
    "stealthType": "STEALTH_TYPE_1",
    "label": "string"
  }
}

List tripsDeprecated

Request

Retrieves the list of trips associated with an organization.

Deprecation notice

The List Trips /v2/list-organisation-trips endpoint has been deprecated. Use the new List trip summaries for a company /v3/trips/companies/{companyId}/list endpoint instead.

Security
Bearer
Bodyapplication/json
organizationIdobject(OrganizationId)required

Organization id for traveler.

organizationId.​idstringrequired
updatedAtobject(DateTimeOffset)

ISO8601 UTC Date Time

pnrTypestringrequired

Type of PNR

Enum"AIR""CAR""RAIL""HOTEL""LIMO""ALL"
customFieldIdsArray of objects(CustomFieldId)Deprecated

List of custom field IDs to filter. This field is not in use and has been deprecated.

curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v2/list-organisation-trips \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationId": {
      "id": "string"
    },
    "updatedAt": {
      "iso8601": "2017-07-21T17:32Z"
    },
    "pnrType": "AIR",
    "customFieldIds": [
      {
        "type": "QUESTION",
        "externalId": "string"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
tripsArray of objects(OrgTripInfo)
Response
application/json
{
  "trips": [
    { … }
  ]
}

PNRs

APIs to manage PNRs within trips.

Operations

Invoicing

APIs to manage invoicing.

Operations

Approval

APIs to manage approvals.

Operations
Copyright © 2025 Spotnana Technology, Inc.