Перейти к основному содержимому
Tell&Go
Назад на портал разработчика
Справочник по APIv1.0.0

Документация по API

Полный справочник по универсальному API агентов Tell&Go. Ищите отели, проверяйте наличие и создавайте бронирования программно.

Базовый адресhttps://api.tellandgo.com/api/v1/agent
Получить ключ API

Документация для ИИ

Скопируйте полную документацию по API для использования с ИИ-агентами и большими языковыми моделями или для импорта в ваши инструменты разработки.

Открыть Markdown

Спецификации API

OpenAPI (Swagger)Коллекция Postman

Справочный текст ниже приведён на английском языке.

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.

TierRate LimitCommission
Free100/hourUp to 2% (margin-capped)
EnterpriseBy arrangementCustom (margin-capped)

Commission: up to 2% of the booking value on completed bookings, capped per booking so Tell & Go keeps its minimum margin after card fees; bookings with thin margins may earn a lower rate or none.

GET/properties/:id

Get Property Details

Retrieve detailed information about a specific property.

Parameters

NameTypeRequiredDescription
idstringRequiredThe unique property identifier
POST/availability

Check Availability

Check real-time availability and pricing for a property.

Body Parameters

NameTypeRequiredDescription
property_idstringRequiredTell&Go property ID returned by /search or /properties/:id.
check_instringRequiredCheck-in date in YYYY-MM-DD format.
check_outstringRequiredCheck-out date in YYYY-MM-DD format. Must be after check_in.
guestsobjectOptionalSingle-room/simple occupancy object. For multi-room requests, send rooms instead.
guests.adultsnumberOptionalNumber of adult guests. Required only when rooms is omitted.
guests.childrennumber[]OptionalArray of child ages. Use [] or omit when there are no children.
roomsarrayOptionalPer-room occupancy for multi-room searches. Each room has adults and optional child ages in children.
residencystringRequiredISO 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

NameTypeRequiredDescription
messagestringRequiredUser message or instruction.
session_idstringOptionalSession ID for multi-turn continuity.
contextobjectOptionalPreviously collected preferences or selected properties.
context.previous_searchesstring[]OptionalPrior search phrases.
context.selected_propertiesstring[]OptionalProperty IDs already selected by the user.
context.collected_preferencesobjectOptionalKnown traveler preferences such as dates, destination, budget, interests, or guests.
include_pricingbooleanOptionalWhen true, include live pricing when enough dates/guests are available.
max_propertiesnumberOptionalMaximum properties to return. Default 5.
max_follow_upsnumberOptionalMaximum 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

NameTypeRequiredDescription
property_idstringRequiredTell&Go property ID returned by /search or /availability.
check_instringRequiredCheck-in date in YYYY-MM-DD format.
check_outstringRequiredCheck-out date in YYYY-MM-DD format. Must be after check_in.
guestsobjectOptionalSingle-room/simple occupancy object. For multi-room quotes, send rooms instead.
guests.adultsnumberOptionalNumber of adult guests. Required only when rooms is omitted.
guests.childrennumber[]OptionalArray of child ages.
roomsarrayOptionalPer-room occupancy for multi-room quotes. Use the same room split from /availability.
residencystringRequiredISO 3166-1 alpha-2 citizenship/residency code used for live pricing.
room_idstringOptionalOptional room code or opaque offer_id returned by /availability to quote a specific live rate.
rate_planstringOptionalOptional 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

NameTypeRequiredDescription
quote_idstringRequiredQuote 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

NameTypeRequiredDescription
quote_idstringRequiredQuote ID returned by /quote.
guestsarrayRequiredGuest 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_namestringRequiredGuest first name.
guests[].last_namestringRequiredGuest last name.
guests[].emailstringOptionalGuest email. Strongly recommended for the primary guest.
guests[].phonestringOptionalGuest phone number.
guests[].is_primarybooleanOptionalMarks the primary guest. If omitted, the first guest is treated as primary.
guests[].is_childbooleanOptionalOptional. Only set when providing accurate child details.
guests[].agenumberOptionalRequired when guests[].is_child is true.
special_requestsstringOptionalSpecial requests for the property.
payment_methodstringOptionalPayment method. Defaults to stripe_checkout. redirect is deprecated.
success_urlstringOptionalOptional HTTPS URL to return the payer to after Stripe-hosted checkout succeeds. booking_id and session_id are appended when missing.
cancel_urlstringOptionalOptional 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.

  1. Call /book with payment_method=stripe_checkout.
  2. Redirect the customer to booking.payment.url.
  3. If you provide success_url and cancel_url, Stripe returns the customer to your URLs. Tell&Go appends booking_id and session_id when they are missing.
  4. 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.
  5. Treat GET /bookings/:id and partner webhooks as the canonical final-status mechanisms.

Partners do not call Tell&Go’s inbound /webhook endpoints; 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 the webhooks:write scope. Endpoint records are scoped to the authenticated partner.

Final Status Events

For hotel checkout final status, subscribe to payment.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, and Tellandgo-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.

StatusCodeDescription
400bad_requestInvalid request parameters
401unauthorizedInvalid or missing API key
404not_foundResource not found
429rate_limitedRate 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);

Готовы начать?

Создайте бесплатный аккаунт и получите ключ API за несколько минут.

Получить ключ APIСвязаться с поддержкой