API Referencev1.0.0

API Documentation

Complete reference for the Tell&Go Universal Agent API. Search properties, check availability, and create bookings programmatically.

Base URLhttps://api.tellandgo.com/api/v1/agent

Get Your API Key

AI-Friendly Documentation

Copy the full API documentation for use with AI agents, LLMs, or import into your development tools.

View Markdown

API Specifications

OpenAPI (Swagger)Postman Collection

Authentication

All API requests require authentication using an API key passed in the X-API-Key header.

Example Request

curl -H "X-API-Key: tg_live_your_api_key" \
  https://api.tellandgo.com/api/v1/agent/search

tg_live_*

Production keys

Use for live production applications. Real data and billing.

tg_test_*

Test/sandbox keys

Use for development and testing. No real bookings created.

Rate Limits

API requests are rate limited based on your subscription tier.

Tier	Rate Limit	Commission
Free	100/hour	2 - 3.5%
Enterprise	10,000+/hour	Custom

POST/search

Search Properties

Search for properties with live accommodation pricing. Requires residency, dates, and either guests or rooms.

Body Parameters

Name	Type	Required	Description
query	string	Required	Natural-language search query.
residency	string	Required	Required ISO 3166-1 alpha-2 citizenship/residency code. Sent to live supplier searches as residency.
session_id	string	Optional	Optional partner-side session identifier for attribution/continuity.
constraints	object	Required	Search constraints containing dates and either guests or rooms.
constraints.destination	string	Optional	Destination, country, city, or region.
constraints.budget_min	number	Optional	Minimum nightly budget in the requested/default currency.
constraints.budget_max	number	Optional	Maximum nightly budget in the requested/default currency.
constraints.currency	string	Optional	ISO currency code. Defaults to USD where pricing is requested.
constraints.dates.check_in	string	Required	Check-in date in YYYY-MM-DD format. Required for live supplier pricing.
constraints.dates.check_out	string	Required	Check-out date in YYYY-MM-DD format.
constraints.guests.adults	number	Optional	Number of adult guests for single-room/simple occupancy. Required when constraints.rooms is omitted.
constraints.guests.children	number[]	Optional	Array of child ages.
constraints.rooms	array	Optional	Per-room occupancy for multi-room live pricing. Required when constraints.guests is omitted.
constraints.amenities	string[]	Optional	Amenity filters such as spa, pool, or restaurant.
constraints.activities	string[]	Optional	Activity/experience filters.
limit	number	Optional	Maximum results to return. Default 10; maximum 50.
offset	number	Optional	Pagination offset. Default 0.

Request Body

{
 "query": "luxury beach resort in maldives with overwater villas",
 "residency": "US",
 "constraints": {
   "destination": "maldives",
   "budget_min": 500,
   "budget_max": 2000,
   "dates": {
     "check_in": "2026-08-01",
     "check_out": "2026-08-07"
    },
   "guests": {
     "adults": 2,
     "children": []
    },
   "amenities": [
     "spa",
     "pool",
     "restaurant"
    ]
  },
 "limit": 10
}

GET/properties/:id

Get Property Details

Retrieve detailed information about a specific property.

Parameters

Name	Type	Required	Description
id	string	Required	The unique property identifier

POST/availability

Check Availability

Check real-time availability and pricing for a property.

Body Parameters

Name	Type	Required	Description
property_id	string	Required	Tell&Go property ID returned by /search or /properties/:id.
check_in	string	Required	Check-in date in YYYY-MM-DD format.
check_out	string	Required	Check-out date in YYYY-MM-DD format. Must be after check_in.
guests	object	Optional	Single-room/simple occupancy object. For multi-room requests, send rooms instead.
guests.adults	number	Optional	Number of adult guests. Required only when rooms is omitted.
guests.children	number[]	Optional	Array of child ages. Use [] or omit when there are no children.
rooms	array	Optional	Per-room occupancy for multi-room searches. Each room has adults and optional child ages in children.
residency	string	Required	ISO 3166-1 alpha-2 citizenship/residency code used for live pricing.

Request Body

{
 "property_id": "clx123abc",
 "check_in": "2025-03-01",
 "check_out": "2025-03-07",
 "residency": "US",
 "rooms": [
   {
     "adults": 1,
     "children": [
       0,
       17
      ]
    },
   {
     "adults": 1,
     "children": [
       10
      ]
    }
  ]
}

POST/chatV2

Agentic Chat

Conversational endpoint for AI-powered property discovery with follow-up questions.

Body Parameters

Name	Type	Required	Description
message	string	Required	User message or instruction.
session_id	string	Optional	Session ID for multi-turn continuity.
context	object	Optional	Previously collected preferences or selected properties.
context.previous_searches	string[]	Optional	Prior search phrases.
context.selected_properties	string[]	Optional	Property IDs already selected by the user.
context.collected_preferences	object	Optional	Known traveler preferences such as dates, destination, budget, interests, or guests.
include_pricing	boolean	Optional	When true, include live pricing when enough dates/guests are available.
max_properties	number	Optional	Maximum properties to return. Default 5.
max_follow_ups	number	Optional	Maximum follow-up questions to return.

Request Body

{
 "message": "I'm looking for a romantic honeymoon destination",
 "session_id": "session_xxx",
 "context": {
   "collected_preferences": {
     "travel_style": [
       "romantic"
      ]
    }
  }
}

POST/quoteV2

Create Quote

Generate a bookable pricing quote with a 15-minute validity window.

Body Parameters

Name	Type	Required	Description
property_id	string	Required	Tell&Go property ID returned by /search or /availability.
check_in	string	Required	Check-in date in YYYY-MM-DD format.
check_out	string	Required	Check-out date in YYYY-MM-DD format. Must be after check_in.
guests	object	Optional	Single-room/simple occupancy object. For multi-room quotes, send rooms instead.
guests.adults	number	Optional	Number of adult guests. Required only when rooms is omitted.
guests.children	number[]	Optional	Array of child ages.
rooms	array	Optional	Per-room occupancy for multi-room quotes. Use the same room split from /availability.
residency	string	Required	ISO 3166-1 alpha-2 citizenship/residency code used for live pricing.
room_id	string	Optional	Optional room code or opaque offer_id returned by /availability to quote a specific live rate.
rate_plan	string	Optional	Optional rate-plan or meal-plan hint.

Request Body

{
 "property_id": "clx123abc",
 "room_id": "room_456",
 "check_in": "2025-03-01",
 "check_out": "2025-03-07",
 "residency": "US",
 "rooms": [
   {
     "adults": 1,
     "children": [
       0,
       17
      ]
    },
   {
     "adults": 1,
     "children": [
       10
      ]
    }
  ]
}

POST/prebookV2

Prebook Quote

Verify or lock a selected quote before payment. Quotes that require final verification return locked; quotes without a prebook phase return not_required.

Body Parameters

Name	Type	Required	Description
quote_id	string	Required	Quote ID returned by /quote.

Request Body

{
 "quote_id": "quote_xxx"
}

POST/bookV2

Create Booking

Create a booking from a valid quote. For multi-room quotes, the quote stores the room split. Provide one valid adult lead guest per room; other occupants from the quote are not auto-populated. Quotes that require prebook must be locked first; /book rejects unverified quotes before payment.

Body Parameters

Name	Type	Required	Description
quote_id	string	Required	Quote ID returned by /quote.
guests	array	Required	Guest details. Must contain one valid adult lead guest per booked room. Remaining occupants are taken from the quote occupancy and are not auto-filled into supplier guest names.
guests[].first_name	string	Required	Guest first name.
guests[].last_name	string	Required	Guest last name.
guests[].email	string	Optional	Guest email. Strongly recommended for the primary guest.
guests[].phone	string	Optional	Guest phone number.
guests[].is_primary	boolean	Optional	Marks the primary guest. If omitted, the first guest is treated as primary.
guests[].is_child	boolean	Optional	Optional. Only set when providing accurate child details.
guests[].age	number	Optional	Required when guests[].is_child is true.
special_requests	string	Optional	Special requests for the property.
payment_method	string	Optional	Payment method. Defaults to stripe_checkout. redirect is deprecated.
success_url	string	Optional	Optional HTTPS URL to return the payer to after Stripe-hosted checkout succeeds. booking_id and session_id are appended when missing.
cancel_url	string	Optional	Optional HTTPS URL to return the payer to if Stripe-hosted checkout is cancelled. booking_id and payment=cancelled are appended when missing.

Request Body

{
 "quote_id": "quote_xxx",
 "guests": [
   {
     "first_name": "John",
     "last_name": "Doe",
     "email": "john@example.com",
     "is_primary": true
    }
  ],
 "special_requests": "Honeymoon celebration",
 "payment_method": "stripe_checkout",
 "success_url": "https://partner.example/bookings/complete",
 "cancel_url": "https://partner.example/bookings/cancelled"
}

Final Booking Status

Payment success does not by itself mean the hotel booking is confirmed. Stripe returns the customer after payment, while Tell&Go finalizes the booking server-to-server and updates the stored booking status.

Call /book with payment_method=stripe_checkout.
Redirect the customer to booking.payment.url.
If you provide success_url and cancel_url, Stripe returns the customer to your URLs. Tell&Go appendsbooking_id and session_id when they are missing.
If you do not provide return URLs, Stripe returns the customer to Tell&Go’s default booking status page. That page may initially show “Payment received, confirming your booking” while backend confirmation is still running.
Treat GET /bookings/:id and partner webhooks as the canonical final-status mechanisms.

Partners do not call Tell&Go’s inbound /webhookendpoints; those are reserved for payment and supplier callbacks into Tell&Go.

Manage Bookings

List, retrieve, and cancel bookings.

GET/bookingsList all bookings

GET/bookings/:idGet booking details

DELETE/bookings/:idCancel booking

Partner Webhooks

Register a partner-owned HTTPS callback URL to receive async booking status events. Webhook management requires an authenticated partner API key with thewebhooks:write scope. Endpoint records are scoped to the authenticated partner.

Final Status Events

For hotel checkout final status, subscribe topayment.failed, booking.confirmed, and booking.failed.

Endpoints

POST/webhooks/endpointsCreate a webhook endpoint

GET/webhooks/endpointsList your webhook endpoints

PATCH/webhooks/endpoints/:idUpdate your endpoint URL, events, description, or active state

POST/webhooks/endpoints/:id/testSend a signed test event

DELETE/webhooks/endpoints/:idDisable an endpoint

GET/webhook-deliveriesList recent delivery attempts

Create Example

curl -X POST https://api.tellandgo.com/api/v1/agent/webhooks/endpoints \
  -H "X-API-Key: tg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://partner.example/webhooks/tellandgo",
    "events": ["booking.confirmed", "booking.failed", "payment.failed"],
    "description": "Production booking status webhook"
  }'

The create response returns a secret once. Store it securely; list and update responses do not return it.

Signature Verification

Tell&Go sends Tellandgo-Event,Tellandgo-Timestamp, andTellandgo-Signature. Verify HMAC-SHA256 over${timestamp}.${rawBody} with the endpoint secret and compare it with the v1 value from the signature header. Reject stale timestamps and always verify against the raw request body.

Tell&Go retries transient failures, including network errors, HTTP 429, and HTTP 5xx responses, up to three total attempts. Other HTTP 4xx responses are treated as non-retryable configuration errors.

Error Handling

All errors follow a consistent format.

Status	Code	Description
400	bad_request	Invalid request parameters
401	unauthorized	Invalid or missing API key
404	not_found	Resource not found
429	rate_limited	Rate limit exceeded

Error Response Format

{
  "error": "bad_request",
  "message": "Missing required field: property_id"
}

Code Examples

Quick-start examples in popular languages.

const API_KEY = 'tg_live_your_key';
const BASE_URL = 'https://api.tellandgo.com/api/v1/agent';

async function searchProperties(query) {
  const response = await fetch(`${BASE_URL}/search`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      query,
      residency: 'US',
      constraints: {
        destination: 'maldives',
        dates: { check_in: '2026-08-01', check_out: '2026-08-07' },
        guests: { adults: 2, children: [] }
      }
    })
  });
  return response.json();
}

// Usage
const results = await searchProperties('luxury maldives resort');
console.log(results.properties);

Ready to get started?

Create your free account and get your API key in minutes.

Get API Key Contact Support