Pardivelle API Documentation

Complete reference for integrating with the Pardivelle OAuth API

v1.0

Quick Start

Get started with the Pardivelle API in minutes

Choose Your Authentication Method

Recommended for Partners

Partner API Keys

Simple API key authentication for displaying experiences and creating reservations on your website.

No OAuth flow required
Rate limiting (1000 req/hour)
Usage analytics
Easy to implement
For User Authorization

OAuth 2.0

Full OAuth flow for accessing user data and performing actions on their behalf.

User profile access
Scoped permissions
Refresh tokens
Industry standard

Partner API Quick Start

1

Create API Key

Generate your API key in the dashboard under API Keys section

2

Add to Headers

Include X-API-Key header in your requests

3

Make API Calls

Start fetching experiences and creating reservations

OAuth 2.0 Quick Start

1

Create OAuth App

Register your application in the OAuth dashboard

2

Get Access Token

Implement OAuth 2.0 flow to get user authorization

3

Make API Calls

Use the access token to call our REST endpoints

Base URL
https://pardivelle.com

API Endpoints

Available endpoints for accessing Pardivelle data

GET
/api/public/experiences
API Key

Get Public Experiences (Partner API)

Retrieve experiences for a specific company using Partner API Key authentication

Headers

X-API-Key
Required

Your Partner API Key (starts with sk_)

Content-Type
Required

Must be application/json

Parameters

company
string
Required

Company slug to filter experiences (e.g., "xieltun")

category
string
Options: accommodation, dining, activity, spa, transportation, entertainment, shopping, other

Filter by experience type

location
string

Filter by city or location name

limit
number

Maximum number of results (default: 20, max: 100)

offset
number

Pagination offset (default: 0)

Rate Limits
1000 requests/hour(Configurable in dashboard)

Response

{
  "experiences": [
    {
      "id": "exp_123",
      "title": "Cenote Sacred Experience",
      "description": "Immerse yourself in mystical waters...",
      "slug": "cenote-sacred-experience",
      "price_range": "$150 USD",
      "duration": "per person",
      "location": "Tulum, Quintana Roo, México",
      "category": "spiritual",
      "featured_image": "https://...",
      "images": [
        "https://..."
      ],
      "rating": 4.9,
      "reviews_count": 87,
      "amenities": [
        "transportation",
        "guide",
        "equipment"
      ],
      "company_profiles": {
        "name": "xieltun",
        "logo_url": "https://...",
        "verified": true
      },
      "spotlight_status": "select"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 4,
    "has_more": false
  }
}
POST
/api/public/reservations
API Key

Create Reservation (Partner API)

Create a new reservation and generate Stripe checkout session

Headers

X-API-Key
Required

Your Partner API Key (starts with sk_)

Content-Type
Required

Must be application/json

Request Body

{
  "experience_id": "exp_123",
  "check_in_date": "2025-12-25",
  "check_out_date": "2025-12-25",
  "guest_count": 2,
  "primary_guest_name": "John Doe",
  "primary_guest_email": "john@example.com",
  "primary_guest_phone": "+1234567890",
  "special_requests": "Vegetarian meal options",
  "origin": "xieltun"
}
Rate Limits
1000 requests/hour(Configurable in dashboard)

Response

{
  "success": true,
  "sessionId": "cs_test_...",
  "url": "https://checkout.stripe.com/...",
  "reservationNumber": "XIE20251012AB12",
  "linkedToUser": false,
  "metadata": {
    "experience_name": "Cenote Sacred Experience",
    "total_amount": 315.75,
    "currency": "USD"
  }
}
GET
/api/oauth/user
profile
email

Get User Information

Retrieve authenticated user profile information

Response

{
  "id": "user_id",
  "name": "John Doe",
  "email": "john@example.com",
  "picture": "https://avatar.url",
  "phone": "+1234567890",
  "luxury_preferences": {
    "budget_range": "luxury",
    "preferred_categories": [
      "spa",
      "dining"
    ]
  },
  "created_at": "2024-01-01T00:00:00Z"
}
GET
/api/oauth/experiences
experiences

Get Experiences

Retrieve available experiences and services

Parameters

company
string

Filter by company name

location
string

Filter by location (city, state, or country)

category
string
Options: accommodation, dining, activity, spa, transportation, entertainment, shopping, other

Filter by experience type

limit
number

Maximum number of results (default: 20)

offset
number

Pagination offset (default: 0)

Response

{
  "experiences": [
    {
      "id": "exp_123",
      "name": "Cenote Adventure Tour",
      "description": "Explore the mystical cenotes...",
      "experience_type": "activity",
      "base_price_amount": 150,
      "base_price_currency": "USD",
      "price_per": "person",
      "min_capacity": 2,
      "max_capacity": 12,
      "city": "Tulum",
      "state": "Quintana Roo",
      "country": "Mexico",
      "featured_image_url": "https://...",
      "average_rating": 4.8,
      "total_reviews": 156,
      "amenities": [
        "transportation",
        "lunch",
        "guide"
      ],
      "highlights": [
        "cenote swimming",
        "cave exploration"
      ],
      "spotlight_status": "select",
      "companies": {
        "name": "Xieltun Tours",
        "logo_url": "https://...",
        "is_verified": true
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 25,
    "has_more": true
  }
}
GET
/api/oauth/destinations
destinations

Get Destinations

Retrieve available destinations and locations

Parameters

type
string
Options: countries, cities, localities, all

Type of destination

region
string

Filter by region

country
string

Filter by country (for cities and localities)

featured
boolean

Only featured destinations

limit
number

Maximum number of results (default: 20)

offset
number

Pagination offset (default: 0)

Response

{
  "destinations": [
    {
      "id": "country_123",
      "name": "Mexico",
      "type": "country",
      "description": "A vibrant country...",
      "continent": "North America",
      "region": "Central America",
      "location": "Mexico",
      "featured_image_url": "https://...",
      "popular_for": [
        "beaches",
        "culture",
        "cuisine"
      ],
      "is_featured": true,
      "is_spotlight_edition": true,
      "total_cities": 15,
      "total_experiences": 127,
      "spotlight_rating": 5
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 47,
    "has_more": true
  }
}

Code Examples

Ready-to-use code snippets in multiple languages

javascript
// OAuth API Example
import { PardiveIleOAuthClient } from '@pardivelle/oauth-client'

const client = new PardiveIleOAuthClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  baseUrl: 'https://pardivelle.com'
})

// Get user profile
const user = await client.getUser()

// Get experiences
const experiences = await client.getExperiences({
  category: 'activity',
  location: 'Tulum',
  limit: 10
})

// Partner API Example (API Key)
const PARTNER_API_KEY = 'sk_xxxxx_xxxxx_xxxxx'

// Fetch experiences for your company
const response = await fetch(
  'https://pardivelle.com/api/public/experiences?company=xieltun&limit=10',
  {
    headers: {
      'X-API-Key': PARTNER_API_KEY,
      'Content-Type': 'application/json'
    }
  }
)
const data = await response.json()

// Create a reservation
const reservationResponse = await fetch(
  'https://pardivelle.com/api/public/reservations',
  {
    method: 'POST',
    headers: {
      'X-API-Key': PARTNER_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      experience_id: 'exp_123',
      check_in_date: '2025-12-25',
      guest_count: 2,
      primary_guest_name: 'John Doe',
      primary_guest_email: 'john@example.com',
      origin: 'xieltun'
    })
  }
)
const reservation = await reservationResponse.json()
// Redirect user to: reservation.url

OAuth Scopes

Available scopes for accessing different data types

profile

Access to user profile information

Required
email

Access to user email address

Optional
experiences

Access to experiences and services data

Optional
destinations

Access to destinations and locations data

Optional

OAuth 2.0 Flow

Step-by-step guide to implement OAuth authentication

1

Authorization Request

Redirect user to authorization URL:

GET https://pardivelle.com/api/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=profile email experiences&
  state=RANDOM_CSRF_TOKEN&
  code_challenge=BASE64URL_SHA256(code_verifier)&
  code_challenge_method=S256
2

Authorization Code Exchange

Exchange code for access token (server-side confidential clients):

POST https://pardivelle.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=ORIGINAL_RANDOM_VERIFIER

Mobile/public clients should use your backend exchange endpoint (or/api/oauth/mobile-exchange) and never ship a client secret.

3

API Requests

Use access token in Authorization header:

GET https://pardivelle.com/api/oauth/user
Authorization: Bearer ACCESS_TOKEN

Error Codes

Common error responses and how to handle them

401 Unauthorized
Authentication

Invalid or expired access token. Refresh token or re-authenticate.

403 Forbidden
Authorization

Insufficient permissions. Check required scopes for the endpoint.

404 Not Found
Resource

Requested resource does not exist or user doesn't have access.

429 Rate Limited
Rate Limit

Too many requests. Wait before making additional requests.

Spotlight Certification Levels

Understanding Spotlight The Best certification status

none

Not Certified

No Spotlight certification

pending

Under Review

Application pending

select

Spotlight Select

Entry level certification

premier

Spotlight Premier

Premium certification

elite

Spotlight Elite

Highest certification

Support & Resources

Additional resources and support channels