Learn how to effectively use the Try it feature in the API documentation.

Use the Try it feature to send sample requests to API endpoints directly from the developer portal. In the Mock (schema only) environment, Try it returns schema-driven mock responses or pre-built example responses. In the Production environment, it sends the request to the live API and returns dynamic responses from your selected test property.

You can select between two different environments (top right corner in the UI):

Mock (schema only) (default):

• Helps to understand the response data schema
• Recommended for all write operations (POST, PUT, PATCH, DELETE)
• Environment for testing without affecting live/test data

Production:

• Make sure to use only test properties as the requests hit the production endpoint.
• Changes will affect your test property data
• Requires valid credentials

Click on any unresolved placeholders to add a value or edit an existing placeholder value.

The portal loads the default request body. Where the specification supports multiple request body examples (for example: Rooms API POST endpoint), you can choose a different request body from the drop-down list.

Some helpful pointers before running a request:

• Authentication (when using production endpoint): Configure your authentication headers

  • Bearer token (JWT) as required. Use the Environments tab.
  • Make sure to manage separate machine accounts for test vs. properties in production.
  • Ensure credentials match your selected environment.

• Parameters: Fill in required parameters

  • Path parameters (like propertyId)
  • Query parameters (like language_code)
  • Request body for POST/PUT operations

• Execute: Click Send to send the request

  • The request is sent to the selected environment
  • When sending requests to the production endpoint, a real HTTP request is made to the API

The Try it feature provides comprehensive response information to the extent supported by the OpenAPI specification:

• 2xx: Success responses (200)
• 4xx: Client errors (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server errors (500 Internal Server Error)

• JSON formatted response data

If the returned response, by default, is unformatted, select the supported Response body format in the UI.

• Content-Type, Content-Length.

The Environments tab allows you to create variables specific to the environment. For example, you can add a variable to hold the value of the propertyId placeholder. The portal inserts the respective value depending on the environment at the time of sending the request.

Most of the endpoints (especially POST/PUT/PATCH/DELETE) require you to add a path or query parameter before sending the request. Path parameters use single braces in the OpenAPI specification (e.g., {propertyId}). The portal's Environments tab lets you store values for these parameters as reusable variables.

• Required: Must be provided to make the request
• Type validation: Ensures correct data types (integer, string, etc.)
• Example: propertyId in /properties/{propertyId}/resource

• Optional: Usually have default values
• Example: language_code with en-us as the default value

• Schema validation: Follows OpenAPI schema definitions
• Example data: Prepopulated with sample values

This section provides some basic practice guidelines.

• Always use separate machine accounts for test properties vs. properties in production.
• When testing with the production endpoint, make sure to use only test properties.

• GET requests are non-mutating, but use authorised test properties when testing against the production endpoint.
• Use valid IDs that exist in your system
• Check response structure for integration planning

• Always use Mock (schema only) environment first
• Verify request payload structure
• Check response for success confirmation
• Test error scenarios with invalid data

• Preferable to use Mock (schema only) environment only
• Understand the operation is irreversible
• Have backup data when testing using test properties

401 Unauthorized

• Check authentication credentials
• Verify token is valid and not expired
• Ensure credentials match the selected environment

400 Bad Request

• Validate request payload against schema
• Check required fields are provided
• Verify data types match specification

404 Not Found

• Confirm the resource ID exists
• Check the endpoint URL is correct
• Verify you have access to the resource

If you encounter issues:

1. Check the response error message for details
2. Verify your request matches the API specification
3. Contact the Connectivity Team for support

This documentation applies to all endpoints in the API. The Try it feature provides a consistent testing experience across all operations.