Provider API Documentation

This document describes the minimal REST API your system should expose so DEV‑EIGHT can check availability for a traveler’s requested dates and room category.

Quick start: Implement a single endpoint that accepts either POST JSON or GET query params and returns JSON with either available boolean or a positive rooms count. Configure your credentials and endpoint in your vendor profile.

1. Endpoint

HTTPS strongly recommended.
Provide a single endpoint URL (e.g. https://provider.example.com/api/availability).

2. Authentication

Choose one and configure it in your vendor profile:

Method	Description	Headers / Transport
none	No authentication	–
apikey	API key in standard header	`X-API-KEY: {api_key}`
bearer	Bearer token	`Authorization: Bearer {api_key}`
basic	HTTP Basic Auth	Username = `api_key`, Password = `api_secret`
header	Custom header	`{auth_header}: {api_key}`

3. Request

DEV‑EIGHT can call your endpoint with either POST JSON, POST form, or GET query params. Default is POST JSON. You can change this in your vendor profile.

3.1 Default field names

By default we send:

{
  "checkin":  "YYYY-MM-DD",
  "checkout": "YYYY-MM-DD",
  "adults":   2,
  "room_category": "standard-room"   // optional; may be omitted or empty
}

If your API uses different parameter names, set the “request map” fields in your vendor profile to match.

3.2 Examples

POST JSON

POST /api/availability HTTP/1.1
Host: provider.example.com
Content-Type: application/json
X-API-KEY: YOUR_KEY

{"checkin":"2025-10-10","checkout":"2025-10-12","adults":2,"room_category":"double"}

POST form-encoded

POST /api/availability HTTP/1.1
Host: provider.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer YOUR_TOKEN

checkin=2025-10-10&checkout=2025-10-12&adults=2&room_category=double

GET with query params

GET /api/availability?checkin=2025-10-10&checkout=2025-10-12&adults=2&room_category=double HTTP/1.1
Host: provider.example.com
Authorization: Bearer YOUR_TOKEN

4. Response

Return JSON with either a boolean available or a numeric rooms > 0. We consider availability true if:

available is true, or
rooms is a positive integer.

4.1 Minimal responses

{"available": true}

{"rooms": 3}

4.2 More detailed response (optional)

{
  "status": "ok",
  "available": false,
  "rooms": 0,
  "message": "Fully booked",
  "rates": []
}

If your fields differ, set “Response Path: Available” and/or “Response Path: Rooms Count” in your vendor profile (dot‑path, e.g. data.availability.available).

5. Timeouts and reliability

Default timeout is 10 seconds; you can configure it in your vendor profile.
Return HTTP 200 on success with a JSON body. Non‑200 codes are treated as failures.

6. Mapping and configuration in DEV‑EIGHT

Endpoint: your URL.
Auth: select method and provide keys/secrets (and custom header name if needed).
Request: choose method (GET/POST) and format (json/form/query).
Field mapping: map our fields to yours (checkin/checkout/adults/room_category).
Response paths: set dot‑paths for availability and rooms if you don’t use defaults.

7. cURL samples

API key header

curl -X POST "https://provider.example.com/api/availability" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_KEY" \
  -d '{"checkin":"2025-10-10","checkout":"2025-10-12","adults":2,"room_category":"double"}'

Bearer token

curl -X POST "https://provider.example.com/api/availability" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"checkin":"2025-10-10","checkout":"2025-10-12","adults":2}'

HTTP Basic

curl -X POST "https://provider.example.com/api/availability" \
  -u "API_KEY:API_SECRET" \
  -d "checkin=2025-10-10&checkout=2025-10-12&adults=2"

8. Test your connection

Open your vendor profile in DEV‑EIGHT.
Fill in your endpoint and credentials, choose auth method, set mappings if needed.
Click “Test connection”.

9. FAQ

Q: We return nested JSON, not plain available.
A: Use response paths (dot‑path) to point to your fields, e.g. data.result.available.

Q: We require GET requests with query params.
A: Set Method=GET and Format=query in your vendor profile.

For questions, contact integration support.