Skip to main content

TVL Platform API - Postman Collection Guide

This guide provides comprehensive instructions for importing, configuring, and using the TVL Platform API Postman collection.

Overview​

The TVL Platform API Postman collection provides a complete set of pre-configured requests for testing and interacting with the TVL vacation rental platform API. It includes:

  • 90+ API endpoints organized by functional domain
  • Automated authentication flow with JWT token management
  • Pre-request and test scripts for validation and debugging
  • Environment configurations for local, staging, and production
  • Common workflow examples for typical use cases
  • Newman CLI support for automated testing

Files Included​

FilePurposeLocation
postman-collection.jsonMain API collection/apis/postman-collection.json
postman-env-local.jsonLocal environment/apis/postman-env-local.json
postman-env-staging.jsonStaging environment/apis/postman-env-staging.json
postman-env-production.jsonProduction environment/apis/postman-env-production.json

Getting Started​

Prerequisites​

  • Postman Desktop App (v10.0 or later) or Postman CLI
  • Access to TVL API (local, staging, or production)
  • Valid Google account for OAuth authentication

1. Import the Collection​

Using Postman Desktop​

  1. Open Postman Desktop
  2. Click Import in the top-left corner
  3. Select File tab
  4. Browse to /apis/postman-collection.json
  5. Click Import

Using Postman CLI​

# Import collection
postman collection import /apis/postman-collection.json

2. Import Environment Files​

Import All Environments​

  1. In Postman, click Environments in the left sidebar
  2. Click Import
  3. Select all three environment files:
    • postman-env-local.json
    • postman-env-staging.json
    • postman-env-production.json
  4. Click Import

Select Active Environment​

  1. Click the environment dropdown in the top-right
  2. Select TVL API - Local (or your target environment)

3. Configure Environment Variables​

After importing, configure the environment variables:

VariableDescriptionExampleRequired
base_urlAPI base URLhttp://localhost:3000/api/v1Yes
api_versionAPI versionv1Yes
jwt_tokenJWT authentication tokenAuto-populated after loginYes
organization_idCurrent organization IDAuto-populatedYes
property_idProperty ID for testingSet manually or auto-populatedNo
unit_idUnit ID for testingSet manually or auto-populatedNo
booking_idBooking ID for testingSet manually or auto-populatedNo

Note: Most variables are automatically populated by test scripts when you execute requests.

Authentication Flow​

The TVL API uses Google OIDC for authentication. Follow these steps to authenticate:

Step 1: Initiate Login​

  1. Open the Authentication folder
  2. Select Initiate Google OIDC Login
  3. Update the redirect_uri in the request body
  4. Click Send
  5. Copy the redirect URL from the Location header

Step 2: Complete OAuth Flow​

  1. Paste the redirect URL in your browser
  2. Complete Google OAuth consent
  3. Copy the code and state parameters from the callback URL

Step 3: Exchange Code for JWT​

  1. Select Handle OAuth Callback request
  2. Paste the code and state values
  3. Click Send
  4. The JWT token will be automatically stored in jwt_token variable
// Example: OAuth callback response handling
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "session": {
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2025-10-25T00:00:00Z"
  },
  "organizations": [
    {
      "id": "org-123",
      "name": "Acme Rentals",
      "role": "admin"
    }
  ]
}

Step 4: Verify Authentication​

  1. Select Get Current User request
  2. Click Send
  3. Verify your user profile and permissions

Token Management​

  • JWT tokens are automatically included in all requests via collection-level auth
  • Tokens are stored as secret environment variables
  • Use Logout request to invalidate tokens
  • Pre-request scripts check for token presence

Collection Structure​

The collection is organized into folders matching the API domains:

Authentication​

  • Initiate Google OIDC Login
  • Handle OAuth Callback
  • Get Current User
  • Logout

Organizations​

  • Create Organization
  • Get Organization
  • Update Organization
  • List Organization Members
  • Invite User to Organization

Properties​

  • List Properties
  • Create Property
  • Get Property
  • Update Property
  • Delete Property

Units​

  • Create Unit
  • Get Unit
  • Update Unit
  • Delete Unit

Availability​

  • Get Unit Calendar
  • Create Availability Block
  • Delete Block

Pricing​

  • Get Unit Pricing
  • Create Price Rule
  • Update Price Rule
  • Delete Price Rule

Quotes​

  • Generate Quote
  • Convert Quote to Hold

Bookings​

  • Confirm Hold to Booking
  • List Bookings
  • Get Booking
  • Cancel Booking

Payments​

  • Create Payment Intent
  • Capture Payment
  • List Payments
  • Create Refund

Payouts​

  • List Payouts
  • Create Payout

Channels​

  • List Channels
  • Register Channel

Listings​

  • List Channel Listings
  • Create Listing

Sync​

  • Trigger Channel Sync
  • Trigger Listing Sync

Connectors​

  • Hostaway Webhook

Reports​

  • Get Revenue Report

Common Workflows​

Workflow 1: Create Property and Unit​

This workflow demonstrates creating a complete property listing:

# 1. Authenticate first (see Authentication Flow)

# 2. Create Property
POST {{base_url}}/properties
Body:
{
  "name": "Beachfront Paradise Villa",
  "slug": "beachfront-paradise-villa",
  "property_type": "villa",
  "address": {
    "street1": "123 Ocean Drive",
    "city": "Miami Beach",
    "state": "FL",
    "postal_code": "33139",
    "country": "US"
  },
  "bedrooms": 5,
  "bathrooms": 4.5
}
# Property ID is auto-stored in environment

# 3. Create Unit
POST {{base_url}}/properties/{{property_id}}/units
Body:
{
  "name": "Entire Villa",
  "slug": "entire-villa",
  "unit_type": "entire_property",
  "max_guests": 12
}
# Unit ID is auto-stored in environment

# 4. Set Pricing
POST {{base_url}}/price-rules
Body:
{
  "unit_id": "{{unit_id}}",
  "rule_type": "base_price",
  "price_cents": 35000
}

# 5. Block Owner Dates
POST {{base_url}}/units/{{unit_id}}/blocks
Body:
{
  "start_date": "2025-12-20",
  "end_date": "2025-12-31",
  "block_type": "owner"
}

Workflow 2: Complete Booking Flow​

This workflow shows the full booking process from quote to confirmation:

# 1. Generate Quote
POST {{base_url}}/quotes
Body:
{
  "unit_id": "{{unit_id}}",
  "check_in_date": "2025-03-15",
  "check_out_date": "2025-03-20",
  "guests": 4
}
# Quote ID is auto-stored in environment

# 2. Convert to Hold
POST {{base_url}}/quotes/{{quote_id}}/hold
# Hold ID is auto-stored in environment

# 3. Create Payment Intent
POST {{base_url}}/payment-intents
Body:
{
  "booking_id": "{{booking_id}}",
  "amount_cents": 150000,
  "currency": "USD",
  "payment_method_id": "pm_card_visa"
}
# Payment ID is auto-stored in environment

# 4. Confirm Booking
POST {{base_url}}/holds/{{hold_id}}/confirm
Body:
{
  "payment_id": "{{payment_id}}"
}
# Booking ID is auto-stored in environment

# 5. Get Booking Details
GET {{base_url}}/bookings/{{booking_id}}

Workflow 3: Channel Integration​

Set up and sync with distribution channels:

# 1. Register Channel
POST {{base_url}}/channels
Body:
{
  "channel_type": "airbnb",
  "name": "Airbnb Main Account",
  "credentials": {
    "api_key": "your_key",
    "api_secret": "your_secret"
  }
}
# Channel ID is auto-stored in environment

# 2. Create Listing
POST {{base_url}}/channels/{{channel_id}}/listings
Body:
{
  "unit_id": "{{unit_id}}",
  "title": "Stunning Beachfront Villa",
  "description": "Experience luxury..."
}
# Listing ID is auto-stored in environment

# 3. Trigger Sync
POST {{base_url}}/channels/{{channel_id}}/sync
Body:
{
  "sync_types": ["availability", "pricing"],
  "force": false
}

Workflow 4: Revenue Reporting​

Generate financial reports:

# 1. Get Revenue Report
GET {{base_url}}/reports/revenue
Params:
  start_date: 2025-01-01
  end_date: 2025-01-31
  group_by: day

# 2. List Payments
GET {{base_url}}/payments
Params:
  start_date: 2025-01-01
  end_date: 2025-01-31
  status: captured

# 3. List Payouts
GET {{base_url}}/payouts
Params:
  start_date: 2025-01-01
  end_date: 2025-01-31

Test Scripts​

The collection includes automated test scripts for validation:

Collection-Level Tests​

Run after every request:

// Response time validation
pm.test('Response time is less than 2000ms', function() {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

// Rate limit monitoring
if (pm.response.headers.has('X-RateLimit-Remaining')) {
    const remaining = pm.response.headers.get('X-RateLimit-Remaining');
    console.log('Rate limit remaining:', remaining);

    if (parseInt(remaining) < 10) {
        console.warn('WARNING: Low rate limit remaining!');
    }
}

Request-Level Tests​

Example from "Create Property":

pm.test('Status code is 201', function() {
    pm.response.to.have.status(201);
});

pm.test('Response has property ID', function() {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('id');
    pm.environment.set('property_id', jsonData.id);
    console.log('Property ID stored:', jsonData.id);
});

Pre-Request Scripts​

Collection-level pre-request script:

// Check if JWT token exists
const jwtToken = pm.environment.get('jwt_token');

if (!jwtToken && pm.request.url.path.indexOf('auth') === -1) {
    console.warn('JWT token is missing. Please authenticate first.');
}

Running Collections with Newman CLI​

Newman is Postman's command-line collection runner for automated testing and CI/CD integration.

Installation​

# Install Newman globally
npm install -g newman

# Install HTML reporter (optional)
npm install -g newman-reporter-htmlextra

Basic Usage​

# Run entire collection with local environment
newman run /apis/postman-collection.json \
  --environment /apis/postman-env-local.json

# Run specific folder
newman run /apis/postman-collection.json \
  --folder "Properties" \
  --environment /apis/postman-env-local.json

# Run with detailed output
newman run /apis/postman-collection.json \
  --environment /apis/postman-env-local.json \
  --reporters cli,json \
  --reporter-json-export results.json

Advanced Options​

# Run with custom delays between requests
newman run /apis/postman-collection.json \
  --environment /apis/postman-env-local.json \
  --delay-request 500

# Run with iterations (useful for load testing)
newman run /apis/postman-collection.json \
  --environment /apis/postman-env-local.json \
  --iteration-count 10

# Run with environment variables override
newman run /apis/postman-collection.json \
  --environment /apis/postman-env-local.json \
  --env-var "jwt_token=your_token_here"

# Generate HTML report
newman run /apis/postman-collection.json \
  --environment /apis/postman-env-local.json \
  --reporters htmlextra \
  --reporter-htmlextra-export report.html

CI/CD Integration​

GitHub Actions Example​

name: API Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Newman
        run: npm install -g newman newman-reporter-htmlextra

      - name: Run API Tests
        run: |
          newman run apis/postman-collection.json \
            --environment apis/postman-env-staging.json \
            --reporters cli,htmlextra \
            --reporter-htmlextra-export test-report.html

      - name: Upload Test Report
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: test-report
          path: test-report.html

Jenkins Pipeline Example​

pipeline {
    agent any

    stages {
        stage('Install Dependencies') {
            steps {
                sh 'npm install -g newman'
            }
        }

        stage('Run API Tests') {
            steps {
                sh '''
                    newman run apis/postman-collection.json \
                      --environment apis/postman-env-staging.json \
                      --reporters cli,json \
                      --reporter-json-export results.json
                '''
            }
        }

        stage('Publish Results') {
            steps {
                publishHTML([
                    reportDir: '.',
                    reportFiles: 'results.json',
                    reportName: 'API Test Results'
                ])
            }
        }
    }
}

Newman with Docker​

# Run tests in Docker container
docker run -v $(pwd)/apis:/etc/newman \
  -t postman/newman:latest \
  run /etc/newman/postman-collection.json \
  --environment /etc/newman/postman-env-local.json

Best Practices​

Security​

  1. Never commit tokens: Keep jwt_token values out of version control
  2. Use environment variables: Store sensitive data in environments, not in collection
  3. Rotate credentials regularly: Update API keys and tokens periodically
  4. Use HTTPS in production: Always use secure connections for production environments

Organization​

  1. Use folders: Keep requests organized by domain
  2. Name consistently: Use clear, descriptive names for requests
  3. Add descriptions: Document what each request does
  4. Share collections: Use Postman workspaces for team collaboration

Testing​

  1. Write assertions: Add test scripts to validate responses
  2. Check status codes: Always verify expected HTTP status codes
  3. Validate data: Check response structure and data types
  4. Monitor performance: Track response times for performance issues

Variables​

  1. Auto-populate IDs: Use test scripts to store IDs automatically
  2. Use placeholders: Reference variables with {{variable_name}}
  3. Environment-specific values: Keep different values per environment
  4. Clear test data: Remove test IDs when switching environments

Troubleshooting​

Common Issues​

Issue: "JWT token is missing"​

Solution:

  1. Run the authentication flow first
  2. Verify token is stored in environment: {{jwt_token}}
  3. Check token hasn't expired (default: 24 hours)

Issue: "404 Not Found"​

Solution:

  1. Verify correct environment is selected
  2. Check base_url is correct
  3. Ensure resource IDs are valid
  4. Confirm API server is running

Issue: "401 Unauthorized"​

Solution:

  1. Re-authenticate to get fresh token
  2. Verify token in Authorization header
  3. Check user has required permissions

Issue: "Rate limit exceeded"​

Solution:

  1. Check X-RateLimit-Reset header
  2. Wait for rate limit window to reset
  3. Reduce request frequency
  4. Contact support for limit increase

Issue: "Environment variables not populating"​

Solution:

  1. Check test scripts are enabled
  2. Verify response is successful (2xx status)
  3. Open Postman Console (View > Show Postman Console) for debugging
  4. Manually set variables if needed

Debug Mode​

Enable detailed logging:

# Newman with debug output
newman run /apis/postman-collection.json \
  --environment /apis/postman-env-local.json \
  --verbose

# Check specific request/response
newman run /apis/postman-collection.json \
  --folder "Authentication" \
  --environment /apis/postman-env-local.json \
  --reporters cli \
  --reporter-cli-no-summary \
  --reporter-cli-no-failures

Postman Console​

View detailed request/response data:

  1. Open Postman Console: View > Show Postman Console
  2. Execute requests
  3. Review:
    • Request headers and body
    • Response headers and body
    • Test script output
    • Variable values

Validation​

Pre-Import Checklist​

Before importing the collection, verify:

  • Postman Desktop App v10.0+ installed
  • API server accessible at target base URL
  • Valid credentials for authentication
  • Network connectivity to API endpoints

Post-Import Validation​

After importing, test the setup:

  1. Verify Collection Import

    • Collection appears in left sidebar
    • All folders are present
    • Requests are organized correctly

  2. Verify Environment Import

    • All three environments imported
    • Variables are defined
    • No syntax errors

  3. Test Authentication

    • Run "Get Current User" (will fail without auth)
    • Complete OAuth flow
    • Run "Get Current User" again (should succeed)

  4. Test Basic Workflow

    • Create organization
    • Create property
    • Create unit
    • Verify IDs are auto-populated

Collection Health Check​

Run this Newman command to validate:

newman run /apis/postman-collection.json \
  --environment /apis/postman-env-local.json \
  --folder "Authentication" \
  --bail

Expected output:

TVL Platform API
→ Authentication
  ↳ Get Current User
    GET http://localhost:3000/api/v1/auth/me [200 OK, 1.2KB, 145ms]
    ✓ Status code is 200
    ✓ Response has user and organization

┌─────────────────────────┬──────────┬──────────┐
│                         │ executed │   failed │
├─────────────────────────┼──────────┼──────────┤
│              iterations │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│                requests │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│            test-scripts │        2 │        0 │
├─────────────────────────┼──────────┼──────────┤
│      prerequest-scripts │        1 │        0 │
└─────────────────────────┴──────────┴──────────┘

Additional Resources​

External Resources​

Support​

Changelog​

Version 1.0.0 (2025-10-24)​

Initial Release

  • Complete API collection with 90+ endpoints
  • Three environment configurations (local, staging, production)
  • Automated authentication flow with JWT management
  • Pre-request and test scripts
  • Common workflow examples
  • Newman CLI support
  • Comprehensive documentation

Features

  • Collection-level authentication
  • Automatic variable population
  • Rate limit monitoring
  • Response time validation
  • Error handling

Known Limitations

  • OAuth flow requires manual browser interaction
  • Some endpoints require specific permissions
  • Rate limits vary by plan tier

Contributing​

To improve this collection:

  1. Test new endpoints thoroughly
  2. Add test scripts for validation
  3. Update documentation
  4. Submit changes via pull request

Last Updated: 2025-10-24 Version: 1.0.0 Maintained By: TVL API Team