Base URL & Protocol

When working with the TrackVia API, it’s critical to understand the proper base URL format and protocol requirements. This guide explains how to construct your API requests to ensure secure, reliable communication with TrackVia servers.

Protocol Requirements

The TrackVia API requires all communications to use HTTPS (HTTP Secure). You should always include the protocol as part of the base URL in your API requests.

⚠️

Always use HTTPS: All API communications must use https:// as the protocol. While HTTP requests may be automatically redirected, explicitly using HTTPS is strongly recommended for security and reliability.

Why HTTPS Matters

HTTPS encrypts all data transmitted between your application and TrackVia servers, protecting sensitive information like authentication tokens, API keys, and your business data from interception or tampering.

Base URL Structure

The base URL for TrackVia API requests follows this format:

https://go.trackvia.com

All API endpoints are relative to this base URL. For example, to retrieve records from a view, you would make a request to:

https://go.trackvia.com/openapi/views/{viewId}/records

Custom Subdomains

If your organization has a custom subdomain configured, you can replace go with your specific subdomain:

https://yourcompany.trackvia.com

For example:

https://yourcompany.trackvia.com/openapi/views/{viewId}/records

Private Environments: If you’re in a private environment, you must specify your custom subdomain. The standard go.trackvia.com URL will not work for private deployments.

Security: HSTS Behavior

TrackVia enforces HTTP Strict Transport Security (HSTS) on all application servers. Understanding how HSTS works helps explain why you should always specify HTTPS in your requests.

Browsers and HSTS

Modern web browsers automatically enforce HSTS client-side. Once a browser receives a valid Strict-Transport-Security header from a secure HTTPS response, it will automatically upgrade any future HTTP requests to HTTPS before the request is even sent.

If the TLS handshake fails (for example, due to an invalid certificate or unsupported protocol), the browser will hard-fail with no option to proceed.

SDKs, CLI Tools, and HTTP Libraries

Many SDKs, command-line tools, and HTTP libraries do not honor HSTS unless explicitly configured to do so. Instead, they rely entirely on the server’s behavior:

301 Redirect: TrackVia returns a 301 Moved Permanently redirect from HTTP to HTTPS. This redirect upgrades the connection and encrypts subsequent traffic.
Best Practice: Despite the redirect, you should always explicitly specify https:// in your base URL to avoid the initial unencrypted request.

Key Takeaway: While TrackVia redirects HTTP to HTTPS for compatibility, always use https:// explicitly in your API client configuration for optimal security.

Examples

Here are examples of properly formatted TrackVia API URLs. Note that while these examples use GET, the base URL structure applies to all HTTP methods.

Standard Environment

GET https://go.trackvia.com/openapi/views/123/records?user_key=YOUR_API_KEY

Custom Subdomain

GET https://acme-corp.trackvia.com/openapi/views/123/records?user_key=YOUR_API_KEY

Private Environment

GET https://private-customer.trackvia.com/openapi/views/123/records?user_key=YOUR_API_KEY

URL & Protocol Best Practices

When configuring your API client, keep these protocol-specific tips in mind:

Always specify HTTPS: Include https:// in your base URL configuration, never rely on automatic redirects.
Verify your base URL: Confirm whether you’re using the standard go.trackvia.com domain or a custom subdomain. Check with your TrackVia administrator if you’re unsure.
Private environments require subdomains: If your organization uses a private TrackVia environment, you must use your specific subdomain—the standard URL will not work.
Use environment variables: Store your base URL in an environment variable or configuration file so you can easily switch between environments (sandbox, production, private) without changing code.

API Development Best Practices: Learn broader strategies for efficient API usage, including view optimization and rate limiting.
API Keys: Learn how to generate the keys needed to authenticate your requests.

Whitelisted Groovy Classes API Users