Tirth API · Reference
API reference
Hosts
Every operation can also answer
validation_failed400unauthenticated401forbidden403rate_limited429internal500unavailable503
Catalogue
GET /v2/pujas
List live pujas, a page at a time, or those changed since a moment.
Parameters
updated_sincequerycursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredkindrequirednamerequiredsummaryrequiredperformed_atrequiredidrequirednamerequired
cityrequiredidrequirednamerequired
placesrequiredidrequirednamerequired
booking_typerequiredsolemnrequireddurationrequiredminutesrequireddaysrequirednightsrequired
variantsrequiredidrequirednamerequiredmax_namesrequiredoptionsrequired
inclusionsrequiredexclusionsrequiredwhat_you_receiverequiredadd_on_idsrequiredcancellation_policyrequirednamerequiredbandsrequiredhours_before_startrequiredcharge_bprequired
imagesrequiredurlrequiredaltrequiredcreditrequiredwidthrequiredheightrequired
reference_pricerequiredamount_paiserequiredunitrequiredgstrequiredlabelrequired
page_urlrequiredchecked_onrequiredupdated_atrequired
next_cursorrequired
GET /v2/pujas/{id}
Read one puja.
Parameters
idpathrequired
Responses
200 OK
idrequiredkindrequirednamerequiredsummaryrequiredperformed_atrequiredidrequirednamerequired
cityrequiredidrequirednamerequired
placesrequiredidrequirednamerequired
booking_typerequiredsolemnrequireddurationrequiredminutesrequireddaysrequirednightsrequired
variantsrequiredidrequirednamerequiredmax_namesrequiredoptionsrequired
inclusionsrequiredexclusionsrequiredwhat_you_receiverequiredadd_on_idsrequiredcancellation_policyrequirednamerequiredbandsrequiredhours_before_startrequiredcharge_bprequired
imagesrequiredurlrequiredaltrequiredcreditrequiredwidthrequiredheightrequired
reference_pricerequiredamount_paiserequiredunitrequiredgstrequiredlabelrequired
page_urlrequiredchecked_onrequiredupdated_atrequired
Its own error codes
not_found404
GET /v2/samuhik-pujas
List live samuhik pujas, a page at a time.
Parameters
updated_sincequerycursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredkindrequirednamerequiredsummaryrequiredperformed_atrequiredidrequirednamerequired
cityrequiredidrequirednamerequired
placesrequiredidrequirednamerequired
booking_typerequiredsolemnrequireddurationrequiredminutesrequireddaysrequirednightsrequired
variantsrequiredidrequirednamerequiredmax_namesrequiredoptionsrequired
inclusionsrequiredexclusionsrequiredwhat_you_receiverequiredadd_on_idsrequiredcancellation_policyrequirednamerequiredbandsrequiredhours_before_startrequiredcharge_bprequired
imagesrequiredurlrequiredaltrequiredcreditrequiredwidthrequiredheightrequired
reference_pricerequiredamount_paiserequiredunitrequiredgstrequiredlabelrequired
page_urlrequiredchecked_onrequiredupdated_atrequired
next_cursorrequired
GET /v2/samuhik-pujas/{id}
Read one samuhik puja.
Parameters
idpathrequired
Responses
200 OK
idrequiredkindrequirednamerequiredsummaryrequiredperformed_atrequiredidrequirednamerequired
cityrequiredidrequirednamerequired
placesrequiredidrequirednamerequired
booking_typerequiredsolemnrequireddurationrequiredminutesrequireddaysrequirednightsrequired
variantsrequiredidrequirednamerequiredmax_namesrequiredoptionsrequired
inclusionsrequiredexclusionsrequiredwhat_you_receiverequiredadd_on_idsrequiredcancellation_policyrequirednamerequiredbandsrequiredhours_before_startrequiredcharge_bprequired
imagesrequiredurlrequiredaltrequiredcreditrequiredwidthrequiredheightrequired
reference_pricerequiredamount_paiserequiredunitrequiredgstrequiredlabelrequired
page_urlrequiredchecked_onrequiredupdated_atrequired
Its own error codes
not_found404
GET /v2/packages
List live yatra packages, a page at a time.
Parameters
updated_sincequerycursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredkindrequirednamerequiredsummaryrequiredperformed_atrequiredidrequirednamerequired
cityrequiredidrequirednamerequired
placesrequiredidrequirednamerequired
booking_typerequiredsolemnrequireddurationrequiredminutesrequireddaysrequirednightsrequired
variantsrequiredidrequirednamerequiredmax_namesrequiredoptionsrequired
inclusionsrequiredexclusionsrequiredwhat_you_receiverequiredadd_on_idsrequiredcancellation_policyrequirednamerequiredbandsrequiredhours_before_startrequiredcharge_bprequired
imagesrequiredurlrequiredaltrequiredcreditrequiredwidthrequiredheightrequired
reference_pricerequiredamount_paiserequiredunitrequiredgstrequiredlabelrequired
page_urlrequiredchecked_onrequiredupdated_atrequired
next_cursorrequired
GET /v2/packages/{id}
Read one yatra package.
Parameters
idpathrequired
Responses
200 OK
idrequiredkindrequirednamerequiredsummaryrequiredperformed_atrequiredidrequirednamerequired
cityrequiredidrequirednamerequired
placesrequiredidrequirednamerequired
booking_typerequiredsolemnrequireddurationrequiredminutesrequireddaysrequirednightsrequired
variantsrequiredidrequirednamerequiredmax_namesrequiredoptionsrequired
inclusionsrequiredexclusionsrequiredwhat_you_receiverequiredadd_on_idsrequiredcancellation_policyrequirednamerequiredbandsrequiredhours_before_startrequiredcharge_bprequired
imagesrequiredurlrequiredaltrequiredcreditrequiredwidthrequiredheightrequired
reference_pricerequiredamount_paiserequiredunitrequiredgstrequiredlabelrequired
page_urlrequiredchecked_onrequiredupdated_atrequired
Its own error codes
not_found404
GET /v2/add-ons
List the add-ons products may be sold with.
Parameters
updated_sincequerycursorquerylimitquery
Responses
200 OK
itemsrequiredidrequirednamerequiredunitrequiredproduct_idsrequiredupdated_atrequired
next_cursorrequired
GET /v2/add-ons/{id}
Read one add-on.
Parameters
idpathrequired
Responses
200 OK
idrequirednamerequiredunitrequiredproduct_idsrequiredupdated_atrequired
Its own error codes
not_found404
GET /v2/search
Find products by words in their name or their city's name.
Parameters
qqueryrequiredkindquerylimitquery
Responses
200 OK
itemsrequiredidrequiredkindrequirednamerequiredsummaryrequiredperformed_atrequiredidrequirednamerequired
cityrequiredidrequirednamerequired
placesrequiredidrequirednamerequired
booking_typerequiredsolemnrequireddurationrequiredminutesrequireddaysrequirednightsrequired
variantsrequiredidrequirednamerequiredmax_namesrequiredoptionsrequired
inclusionsrequiredexclusionsrequiredwhat_you_receiverequiredadd_on_idsrequiredcancellation_policyrequirednamerequiredbandsrequiredhours_before_startrequiredcharge_bprequired
imagesrequiredurlrequiredaltrequiredcreditrequiredwidthrequiredheightrequired
reference_pricerequiredamount_paiserequiredunitrequiredgstrequiredlabelrequired
page_urlrequiredchecked_onrequiredupdated_atrequired
Availability
GET /v2/pujas/{id}/availability
A puja's dates and time windows that can be booked.
Parameters
fromqueryrequiredtoqueryrequiredvariant_idqueryidpathrequired
Responses
200 OK
product_idrequireddatesrequireddaterequireddaterequiredtithirequired
availablerequiredon_requestrequiredwindowsrequiredwindowrequiredlabelrequiredavailablerequiredon_requestrequired
date_being_confirmedrequired
Its own error codes
not_found404
GET /v2/samuhik-pujas/{id}/sessions
A samuhik puja's sessions that can be booked.
Parameters
fromqueryrequiredtoqueryrequiredvariant_idqueryidpathrequired
Responses
200 OK
product_idrequiredsessionsrequiredidrequireddaterequireddaterequiredtithirequired
starts_atrequiredsankalp_closes_atrequiredavailablerequiredon_requestrequired
date_being_confirmedrequired
Its own error codes
not_found404
GET /v2/packages/{id}/departures
A package's departures and start dates that can be booked.
Parameters
fromqueryrequiredtoqueryrequiredvariant_idqueryidpathrequired
Responses
200 OK
product_idrequireddeparturesrequireddeparture_idrequiredstartrequireddaterequiredtithirequired
endrequireddaterequiredtithirequired
availablerequiredon_requestrequired
Its own error codes
not_found404
GET /v2/availability
Dates for up to 20 products at once, over at most 31 days.
Parameters
idsqueryrequiredfromqueryrequiredtoqueryrequired
Responses
200 OK
productsrequiredproduct_idrequiredkindrequireddatesrequireddaterequireddaterequiredtithirequired
option_idrequiredavailablerequiredon_requestrequired
date_being_confirmedrequired
GET /v2/availability/changes
Changes to products and their dates, oldest first, from a cursor.
Parameters
cursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredtyperequiredproduct_idrequiredoption_idrequiredoccurred_atrequired
next_cursorrequiredhas_morerequired
Calendar
GET /v2/calendar/cities
The calendar's cities, whose IDs the other calendar routes take.
Responses
200 OK
citiesrequiredidrequirednamerequired
defaultsrequiredpanchangrequiredfestivalsrequired
GET /v2/calendar/tithis
Each date's tithi at sunrise in a city, over at most 60 days.
Parameters
cityqueryrequiredfromqueryrequiredtoqueryrequired
Responses
200 OK
cityrequireditemsrequireddaterequiredweekdayrequiredlabelrequiredtithirequired
GET /v2/calendar/festivals
Festivals in a city, over at most 92 days.
Parameters
cityqueryfromqueryrequiredtoqueryrequired
Responses
200 OK
cityrequiredidrequirednamerequired
itemsrequiredobservance_idrequirednamerequireddaterequiredlabelrequiredtithirequiredsecond_dayrequireddaterequiredlabelrequired
statusrequired
Quotes
POST /v2/quotes
Price a selection at the Agent net, locked 30 minutes, with seats held on request.
Request body
variant_idrequiredservice_daterequireddeparture_idpuja_event_idslot_idtravellersrequiredadultschild_with_bedchild_without_bedinfantpeople
quantityadd_onsadd_on_idrequiredquantity
hold_seats
Responses
201 Created
quote_idrequiredconfirmationrequiredlinesrequiredproduct_idrequiredproduct_kindrequiredtitlerequiredvariant_idrequiredvariant_namerequiredservice_daterequiredservice_torequireddeparture_idrequiredpuja_event_idrequiredslot_idrequiredtravellersrequiredadultsrequiredchild_with_bedrequiredchild_without_bedrequiredinfantrequiredpeoplerequired
net_totalrequirednet_amountrequiredtirth_gstrequiredreference_retail_pricerequired
net_totalrequirednet_amountrequiredtirth_gstrequiredreference_retail_pricerequiredprice_locked_untilrequiredprice_locked_until_textrequiredholdrequiredseatsrequiredheld_untilrequiredheld_until_textrequired
decision_within_hoursrequired
Its own error codes
not_found404not_bookable409hold_refused409holds_disabled409quotes_blocked429idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
Bookings and proof
GET /v2/bookings
Find a booking by partner_reference, or list bookings whose status changed.
Parameters
partner_referencequerystatusqueryupdated_sincequerycursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredpartner_referencerequiredstatusrequiredversionrequirednet_totalrequiredservice_fromrequiredupdated_atrequired
next_cursorrequired
POST /v2/bookings
Book a quote with your partner_reference, paid from your credit.
Request body
quote_idrequiredpartner_referencerequiredsankalpnamesrequirednamerequiredgotrarequired
join_as
travellersnamerequiredage_bandrequiredis_leadphone_e164special_needs
Responses
201 Created
idrequiredpartner_referencerequiredstatusrequiredversionrequiredconfirmationrequireddecide_byrequireddecide_by_textrequirednet_totalrequirednet_amountrequiredtirth_gstrequiredlinesrequiredbooking_idrequiredproduct_idrequiredproduct_kindrequiredtitlerequiredvariant_namerequiredservice_fromrequireddaterequiredlabelrequiredtithirequirednoterequired
service_torequiredcore_statusrequiredseatsrequirednet_totalrequirednet_amountrequiredtirth_gstrequiredcancellation_policyrequirednamerequiredtiersrequiredmin_hours_beforerequiredcharge_bprequired
linesrequired
sankalp_namesrequirednamerequiredgotrarequired
travellersrequirednamerequiredage_bandrequiredis_leadrequired
cancellationrequiredrefund_paiserequiredrequested_atrequiredstatusrequired
amendmentsrequiredidrequiredstatusrequiredkindrequireddifference_paiserequiredrequested_atrequired
cancellation_in_reviewrequiredrequested_atrequired
created_atrequired
Its own error codes
not_found404quote_used409quote_expired410credit_insufficient402partner_reference_taken409idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
GET /v2/bookings/{id}
Read one booking: status, version, lines, money and policy.
Parameters
idpathrequired
Responses
200 OK
idrequiredpartner_referencerequiredstatusrequiredversionrequiredconfirmationrequireddecide_byrequireddecide_by_textrequirednet_totalrequirednet_amountrequiredtirth_gstrequiredlinesrequiredbooking_idrequiredproduct_idrequiredproduct_kindrequiredtitlerequiredvariant_namerequiredservice_fromrequireddaterequiredlabelrequiredtithirequirednoterequired
service_torequiredcore_statusrequiredseatsrequirednet_totalrequirednet_amountrequiredtirth_gstrequiredcancellation_policyrequirednamerequiredtiersrequiredmin_hours_beforerequiredcharge_bprequired
linesrequired
sankalp_namesrequirednamerequiredgotrarequired
travellersrequirednamerequiredage_bandrequiredis_leadrequired
cancellationrequiredrefund_paiserequiredrequested_atrequiredstatusrequired
amendmentsrequiredidrequiredstatusrequiredkindrequireddifference_paiserequiredrequested_atrequired
cancellation_in_reviewrequiredrequested_atrequired
created_atrequired
Its own error codes
not_found404
GET /v2/bookings/{id}/proof
A booking's proof as signed links valid 24 hours.
Parameters
idpathrequired
Responses
200 OK
booking_idrequireditemsrequiredkindrequiredurlrequiredtracking_refrequirednames_read_at_secondsrequiredshared_atrequired
links_valid_untilrequiredlinks_valid_until_textrequired
Its own error codes
not_found404
GET /v2/bookings/{id}/proof/{index}
Open one piece of proof through its signed link.
Parameters
expiresqueryrequiredsignaturequeryrequiredidpathrequiredindexpathrequired
Responses
200 OK
Its own error codes
not_found404gone410
Change feed
GET /v2/booking-changes
Status changes after the last one you acknowledged, oldest first.
Parameters
afterquerylimitquery
Responses
200 OK
itemsrequiredevent_idrequiredbooking_idrequiredpartner_referencerequiredstatusrequiredversionrequiredoccurred_atrequired
next_cursorrequiredlast_acked_event_idrequired
POST /v2/booking-changes/ack
Acknowledge the change feed up to an event.
Request body
event_idrequired
Responses
200 OK
last_acked_event_idrequired
Its own error codes
not_found404
Amendments
POST /v2/bookings/{id}/amendment-quotes
What a change to a booking would cost now. Nothing is written.
Parameters
idpathrequired
Request body
changerequiredOption 1
kindrequirednew_daterequireddeparture_idpuja_event_idslot_id
Option 2
kindrequiredtravellersrequiredadultschild_with_bedchild_without_bedinfantpeople
quantity
Option 3
kindrequirednew_variant_idrequireddeparture_idslot_id
Responses
200 OK
booking_idrequiredchangerequiredOption 1
kindrequirednew_daterequireddeparture_idpuja_event_idslot_id
Option 2
kindrequiredtravellersrequiredadultsrequiredchild_with_bedrequiredchild_without_bedrequiredinfantrequiredpeoplerequired
quantity
Option 3
kindrequirednew_variant_idrequireddeparture_idslot_id
current_total_paiserequirednew_total_paiserequireddifference_paiserequiredprice_locked_untilrequiredprice_locked_until_textrequired
Its own error codes
not_found404not_amendable409idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
POST /v2/bookings/{id}/amendments
Ask for a change to a booking. Tirth's team makes it.
Parameters
idpathrequired
Request body
changerequiredOption 1
kindrequirednew_daterequireddeparture_idpuja_event_idslot_id
Option 2
kindrequiredtravellersrequiredadultschild_with_bedchild_without_bedinfantpeople
quantity
Option 3
kindrequirednew_variant_idrequireddeparture_idslot_id
expected_difference_paise
Responses
201 Created
idrequiredbooking_idrequiredstatusrequiredkindrequireddifference_paiserequirednew_total_paiserequiredrequested_atrequired
Its own error codes
not_found404not_amendable409price_changed412idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
Cancellations and refunds
GET /v2/bookings/{id}/cancellation-quote
The refund under the booking's frozen policy, with a signed token.
Parameters
idpathrequired
Responses
200 OK
booking_idrequiredpaid_paiserequiredcharge_bprequiredcharge_paiserequiredrefund_paiserequiredvalid_untilrequiredvalid_until_textrequiredquote_tokenrequiredpolicy_linesrequired
Its own error codes
not_found404not_cancellable409cancellation_closed409
POST /v2/bookings/{id}/cancellations
Cancel a booking before its start. The refund goes to your credit.
Parameters
idpathrequired
Request body
quote_tokenrefundreasonrequired
Responses
200 OK
booking_idrequiredstatusrequiredrefund_paiserequiredcancellation_idsrequired
202 Accepted
booking_idrequiredstatusrequiredrefund_paiserequiredcancellation_idsrequired
Its own error codes
not_found404not_cancellable409cancellation_closed409quote_expired410idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
GET /v2/refunds
Refunds to your credit, newest first.
Parameters
cursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredbooking_idrequiredamount_paiserequiredstatusrequiredreasonrequiredlabelrequiredcreated_atrequiredcompleted_atrequired
next_cursorrequired
GET /v2/refunds/{id}
Read one refund.
Parameters
idpathrequired
Responses
200 OK
idrequiredbooking_idrequiredamount_paiserequiredstatusrequiredreasonrequiredlabelrequiredcreated_atrequiredcompleted_atrequired
Its own error codes
not_found404
Credit and invoices
GET /v2/credit
Your credit balance, its open lots and transfers waiting to be matched.
Responses
200 OK
balance_paiserequiredlow_balance_alert_paiserequiredlowrequiredlotsrequiredidrequiredamount_paiserequiredremaining_paiserequiredopened_atrequiredexpires_onrequired
waiting_for_verification_paiserequired
GET /v2/credit/transactions
Every credit movement, newest first.
Parameters
cursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredtyperequiredlabelrequiredreferencerequiredtyperequiredidrequired
amount_paiserequiredoccurred_atrequiredlot_idsrequiredlot_expires_onrequired
next_cursorrequired
GET /v2/credit/statements/{month}
The statement of a month that has ended, as CSV.
Parameters
monthpathrequired
Responses
200 OK
Its own error codes
not_found404
POST /v2/credit/top-ups
Tell Tirth of a bank transfer already sent, with its UTR.
Request body
amount_paiserequiredreferencerequired
Responses
201 Created
idrequiredamount_paiserequiredstatusrequiredreferencerequiredcreated_atrequiredpaid_atrequiredinstructionsrequired
Its own error codes
idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
GET /v2/invoices
The GST documents Tirth issued to your company.
Parameters
cursorquerylimitquery
Responses
200 OK
itemsrequiredidrequirednumberrequiredtyperequiredbooking_idrequiredplace_of_supplyrequiredtaxable_paiserequiredcgst_paiserequiredsgst_paiserequiredigst_paiserequiredtotal_paiserequiredissued_atrequiredoriginal_numberrequiredpdf_readyrequired
next_cursorrequired
Webhooks
GET /v2/webhook-endpoints
Your webhook endpoints in this environment.
Responses
200 OK
itemsrequiredidrequiredurlrequiredevent_typesrequiredstatusrequireddisabled_reasonrequiredfailing_sincerequiredsecret_rotated_atrequiredcreated_atrequired
POST /v2/webhook-endpoints
Add an endpoint. Its signing secret is shown once.
Request body
urlrequiredevent_types
Responses
201 Created
idrequiredurlrequiredevent_typesrequiredstatusrequireddisabled_reasonrequiredfailing_sincerequiredsecret_rotated_atrequiredcreated_atrequiredsecretrequired
Its own error codes
endpoint_limit_reached409conflict409idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
DELETE /v2/webhook-endpoints/{id}
Switch an endpoint off. Its waiting deliveries stop.
Parameters
idpathrequired
Responses
200 OK
Its own error codes
not_found404
POST /v2/webhook-endpoints/{id}/rotate-secret
A new signing secret, with the old one still signing for 24 hours.
Parameters
idpathrequired
Responses
200 OK
idrequiredurlrequiredevent_typesrequiredstatusrequireddisabled_reasonrequiredfailing_sincerequiredsecret_rotated_atrequiredcreated_atrequiredsecretrequired
Its own error codes
not_found404conflict409idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
GET /v2/webhook-deliveries
Deliveries from the last 30 days, newest first.
Parameters
endpoint_idquerycursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredendpoint_idrequiredevent_idrequiredtyperequiredbooking_idrequiredstatusrequiredattemptsrequiredresponse_coderequiredresponse_msrequiredlast_errorrequirednext_attempt_atrequiredcreated_atrequired
next_cursorrequired
Cases
GET /v2/cases
Your cases with their messages.
Parameters
statusquerycursorquerylimitquery
Responses
200 OK
itemsrequiredidrequiredbooking_idrequiredpartner_referencerequiredcategoryrequiredpriorityrequiredstatusrequiredfirst_reply_due_atrequiredresolution_due_atrequiredcreated_atrequiredmessagesrequiredidrequiredfromrequiredbodyrequiredcreated_atrequired
next_cursorrequired
POST /v2/cases
Ask Tirth support about one of your bookings.
Request body
booking_idpartner_referencecategoryrequiredmessagerequired
Responses
201 Created
idrequiredbooking_idrequiredpartner_referencerequiredcategoryrequiredpriorityrequiredstatusrequiredfirst_reply_due_atrequiredresolution_due_atrequiredcreated_atrequiredmessagesrequiredidrequiredfromrequiredbodyrequiredcreated_atrequired
Its own error codes
not_found404
Privacy requests
POST /v2/privacy-requests
File a pilgrim's request for a copy of their data, or to delete it.
Request body
booking_idpartner_referencekindrequiredtraveller_ids
Responses
201 Created
idrequiredkindrequiredstatusrequiredbooking_idrequiredpartner_referencerequiredtraveller_idsrequireddue_atrequiredrequested_atrequired
Its own error codes
not_found404idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
Sandbox
POST /v2/sandbox/bookings/{id}/advance
Move a sandbox booking one stage on, and send that stage's webhook.
Parameters
idpathrequired
Responses
200 OK
booking_idrequiredprevious_statusrequiredstatusrequiredversionrequired
Its own error codes
sandbox_only404not_found404not_advanceable409idempotency_key_required400idempotency_key_reused409idempotency_in_progress409
