TrayiStats Supply API v1.0 • Live Data Platform

The Source of Truth for Supply Chain Data

Integrate TrayiStats Supply API to access real-time survey inventory, global market intelligence, and supplier data directly within your stack.

<50ms Latency

OAuth / Key Auth

Multi-Locale

99.99% Uptime

View API Specs Sandbox Environment

quick_start.sh

# Fetch active surveys

curl -X GET \
"https://surveys-sandbox.trayistats.com/supply/api/available-surveys" \
-H "access-key: YOUR_API_KEY"

● 200 OKResponse: application/json

Why Choose TrayiStats?

Built for organizations that demand speed, reliability, and scalability, TrayiStats simplifies the complexity of global market research and survey management. Our platform enables seamless API integration, intelligent traffic routing, real-time reporting, and secure data processing.

Key Enterprise Capabilities

High-performance platform designed for enterprise-scale operations.

Reliable APIs with low-latency sub-100ms response times.

Real-time survey inventory and dynamic traffic management.

Global market coverage with localization support.

Secure, scalable, and highly available multi-region architecture.

Comprehensive reporting, analytics, and reconciliation tools.

Environments

Base URLs for the TrayiStats Supply API. Use the Sandbox environment for testing and integration before moving to live Production.

Sandbox Endpoint

Testing Sandbox

https://surveys-sandbox.trayistats.com/supply/api

Production Endpoint

Live Production

{BaseUrl}/supply/api

Production base URL placeholder. Custom subdomain assigned upon account setup.

Access Key Provisioning via Email

All API requests require a valid access-key header. Your unique Access Key and Hashing Credentials are provided directly via official email by the TrayiStats team upon account onboarding.

Best Practices

Survey & Attribute API Refresh Behavior

Understanding the refresh behavior and parameter requirements of each API endpoint is essential for efficient integration and optimal system performance.

Qualification Parameters

Format: URL Query Parameters

Qualifications are passed as query parameters using the format Q{AttributeID}={Value}.

Single Select: Q417=65

Multi Select: Q418=3677,3678 (Comma-separated)

Open Ended: Q101=25

Constraint: Panel ID, Transition ID, or Session ID must not exceed 64 characters.

Available Surveys API

Refresh Interval: 15 minutes

The Available Surveys API is refreshed automatically every 15 minutes. This ensures that API consumers receive an up-to-date list containing only active surveys, while paused or inactive surveys are excluded from the response.

Integration Recommendation: Poll this endpoint at 15-minute intervals to maintain synchronization with the system's refresh cycle and ensure respondents are directed only to active projects.

Survey Attributes API

Refresh Behavior: Lifecycle-based

The Survey Attributes API provides attribute data when a survey is created or updated. This data remains consistent throughout the survey's lifecycle and does not change unless the survey is explicitly modified.

Integration Recommendation: Retrieve survey attributes once when a new survey becomes available, or when you detect a change in the survey's lastUpdated timestamp. Frequent polling is unnecessary.

Attributes API

Refresh Behavior: Static metadata

The Attributes API functions as a metadata reference and is independent of survey availability. Attribute definitions (such as demographic questions and response options) do not change based on survey status or activity.

Integration Recommendation: Cache attribute metadata locally. This endpoint requires minimal refresh calls—typically only when adding support for new locales or when notified of metadata updates.

API Reference

The TrayiStats Supply API allows you to programmatically manage surveys, retrieve country lists, and access survey attributes.

Available Surveys

v1.0.0

Retrieves a list of all surveys currently live and available for the authenticated supply partner. This endpoint supports pagination and filtering by country and language.

GEThttps://surveys-sandbox.trayistats.com/supply/api/available-surveys

Headers

Parameter	Data Type	Requirement
access-key	string	Required

A valid API access key is required for live endpoint access.

Survey Object

SurveyResponse

Field Name	Type	Description
surveyId	string	Unique identifier for the survey opportunity.
title	number	Internal title or ID of the survey.
completeGoal	number	Total number of completes desired.
loi	number	Estimated Length of Interview in minutes.
ir	number	Historical Incidence Rate (0-100).
cost	number	Cost Per Interview (CPI) in USD.
countryLocaleId	number	Identifier for the country and locale.
launchedAt	string	Timestamp of survey launch (ISO 8601).
lastUpdated	string	Timestamp of the last update (ISO 8601).
deduplicationStatus	number	Deduplication setting status.
AssociatedClientId	string	Unique identifier for the associated client.
link	string	The survey entry link with placeholders.

Response Status Codes

200 OK

Request was successful and returns valid survey payload.

400 Bad Request

Invalid query parameters or malformed request format.

401 Unauthorized

API Access Key is missing, expired, or unauthorized.

429 Too Many Requests

Rate limit exceeded. Retry after cooling period.

Example Response

Key

Value

GENERATED CURL

RESPONSE200 OK

{
  "success": "boolean",
  "data": {
    "Total": "number",
    "Items": [
      {
        "surveyId": "string | null",
        "title": "number",
        "completeGoal": "number",
        "CompleteRequired": "number",
        "loi": "number",
        "ir": "number",
        "cost": "number (decimal)",
        "countryLocaleId": "number",
        "launchedAt": "string (ISO 8601 datetime)",
        "lastUpdated": "string (ISO 8601 datetime)",
        "deduplicationStatus": "number",
        "AssociatedClientId": "string",
        "IsPulledSurvey": "number",
        "link": "string"
      }
    ]
  }
}

Get Survey by ID

v1.0.0

Retrieve detailed configuration, question structure, and aggregate statistics for a specific survey using its unique identifier. This endpoint includes metadata about response rates.

GEThttps://surveys-sandbox.trayistats.com/supply/api/survey

Path Parameters

Parameter	Type	Description
surveyId required	string	The unique identifier of the survey you want to retrieve. Example: `srv_12345`

Survey Object

SurveyResponse

Field Name	Type	Description
surveyId	string	Unique identifier for the survey opportunity.
title	number	Internal title or ID of the survey.
completeGoal	number	Total number of completes desired.
loi	number	Estimated Length of Interview in minutes.
ir	number	Historical Incidence Rate (0-100).
cost	number	Cost Per Interview (CPI) in USD.
countryLocaleId	number	Identifier for the country and locale.
launchedAt	string	Timestamp of survey launch (ISO 8601).
lastUpdated	string	Timestamp of the last update (ISO 8601).
deduplicationStatus	number	Deduplication setting status.
AssociatedClientId	string	Unique identifier for the associated client.
link	string	The survey entry link with placeholders.

Response Status Codes

200 OK

Returns a Survey Object.

404 Not Found

If the survey with the provided surveyId does not exist.

Example Request

Key

Value

GENERATED CURL

RESPONSE200 OK

{
  "success": "boolean",
  "data": {
    "Total": "number",
    "Items": [
      {
        "surveyId": "string | null",
        "title": "number",
        "completeGoal": "number",
        "CompleteRequired": "number",
        "loi": "number",
        "ir": "number",
        "cost": "number (decimal)",
        "countryLocaleId": "number",
        "launchedAt": "string (ISO 8601 datetime)",
        "lastUpdated": "string (ISO 8601 datetime)",
        "deduplicationStatus": "number",
        "AssociatedClientId": "string",
        "IsPulledSurvey": "number",
        "link": "string"
      }
    ]
  }
}

Survey Attributes

Retrieves a list of specific attributes associated with a survey based on the provided ID. This endpoint allows you to filter attributes by active status and limit the number of results returned for pagination purposes.

GEThttps://surveys-sandbox.trayistats.com/supply/api/survey-attributes

Query Parameters

Name	Type	Description
`surveyId`required	string	The unique identifier of the survey.

Attribute Object

Returns an array of objects with the following schema:

attributeId

number

Unique identifier for the survey attribute.

options

array

Array of selected option IDs or value range strings (e.g. [1, 2], ["18-99"]).

Request

Key

Value

GENERATED CURL

RESPONSE200 OK

{
  "success": true,
  "data": {
    "Total": 3,
    "Items": [
      {
        "attributeId": 1,
        "options": [
          1,
          2
        ]
      },
      {
        "attributeId": 2,
        "options": [
          "18-99"
        ]
      },
      {
        "attributeId": 6,
        "options": [
          90859,
          90860,
          90861,
          90862,
          90863,
          90859,
          90860,
          90861,
          90862,
          90863
        ]
      }
    ]
  }
}

List all countries

v1.0

Returns a list of all supported countries where supply data is available. The response includes the ISO code and default locale for each country.

GEThttps://surveys-sandbox.trayistats.com/supply/api/country

The Country Object

HTTP 200 OK

Each item in the response array represents a supported country entity.

Field	Type	Description
id	string	Unique identifier for the country/locale entity.
localeName	string	Display name of the language/locale (e.g., 'Hindi', 'English').
localeCode	string	Locale identifier code (e.g., 'Hindi-IN', 'English-US').
countryName	string \| null	OptionalCommon name of the country (e.g., 'India', 'USA'). Can be null for certain entries.

Response Status Codes

200 OK

Request was successful and returns a list of countries.

401 Unauthorized

API Key is missing or invalid.

Example Request

Key

Value

GENERATED CURL

RESPONSE200 OK

{
  "success": true,
  "data": {
    "Total": "number",
    "Items": [
      {
        "id": "string",
        "localeName": "string",
        "localeCode": "string",
        "countryName": "string"
      }
    ]
  }
}

Attributes Endpoint

v1.0

Manage and retrieve product attributes for various locales. This endpoint allows you to sync your internal product definitions with our global supply chain standards.

GEThttps://surveys-sandbox.trayistats.com/supply/api/attributes

Query Parameters

Parameter	Type	Required
`countryLocaleId`	string	Required

The country locale identifier (e.g., 4). Determines the language and specific attribute availability.

Attribute Item Object

AttributeItem

Field Name	Type	Description
name	string	Internal identifier name for the attribute (e.g., STANDARD_GENDER, STATE). Used to map the attribute to a known profiling category.
id	number	Unique numeric ID of the attribute. This is the AttributeID used in qualification parameters (e.g., Q1=, Q2=).
text	string	The question text displayed to the respondent (e.g., "What is your gender?").
type	string	Input type of the attribute. Possible values: radio, dropdown, multi-punch, range, open-ended.
options	array	List of valid answer options for this attribute. Empty array for range and open-ended types.
options[].id	number	Unique ID of the option. This value is passed as the qualification answer (e.g., Q1=1 for Male).
options[].text	string	Human-readable label of the option shown to the respondent (e.g., "Male", "Female", "CALIFORNIA").

Common Errors

400Bad Request

Invalid countryLocaleId provided.

401Unauthorized

Authentication token is missing or invalid.

Example Request

200 OK

Response

Key

Value

GENERATED CURL

RESPONSE200 OK

{
  "success": true,
  "data": {
    "Total": 938,
    "Items": [
      {
        "name": "STANDARD_GENDER",
        "id": 1,
        "text": "What is your gender ?",
        "type": "radio",
        "options": [
          {
            "id": 1,
            "text": "Male"
          },
          {
            "id": 2,
            "text": "Female"
          }
        ]
      }
    ]
  }
}

Survey Stats

v1.0.0

Get performance metrics and conversion statistics for a specific survey. This includes both vendor-specific and global completion counts.

GEThttps://surveys-sandbox.trayistats.com/supply/api/survey-stats

Query Parameters

Parameter	Data Type	Requirement
SurveyId	string	Required

Stats Object

SurveyStatsResponse

Field Name	Type	Description
vendorCompletes	number	Total number of completes achieved through the vendor.
globalCompletes	number	Total number of completes achieved globally.
vendorConversion	number	Conversion rate for the vendor (%)
globalConversion	number	Global conversion rate for the survey (%)

Response Status Codes

200 OK

Request was successful and returns valid survey payload.

400 Bad Request

Invalid query parameters or malformed request format.

401 Unauthorized

API Access Key is missing, expired, or unauthorized.

429 Too Many Requests

Rate limit exceeded. Retry after cooling period.

Request

Key

Value

GENERATED CURL

RESPONSE200 OK

{
  "success": true,
  "data": {
    "success": true,
    "Total": 1,
    "Items": [
      {
        "vendorCompletes": 21,
        "globalCompletes": 68,
        "vendorConversion": 0,
        "globalConversion": 4.25
      }
    ]
  }
}

Security

Secure your integration by implementing exit link verification and rotate keys regularly.

Security Protocol for Exit Links

Ensure the integrity of your exit links using the SHA-1 hashing algorithm. This protocol prevents link tampering and validates the source of the traffic.

Important Security Note

Your hashing key is a private secret. Never expose it in client-side code or share it publicly. If your key is compromised, rotate it immediately via the dashboard.

Identify Original Link

Start with the full destination URL you intend to redirect the user to. Ensure it is properly encoded if it contains special characters.

https://example.com/offer?user_id=123

Define Hashing Key

Your unique private hashing key will be securely provided to you via email. This key acts as the salt for generating the hash.

my_secret_key_8823

Concatenation

Concatenate the original link and your hashing key. Do not add any spaces or delimiters between them.

https://example.com/offer?user_id=123my_secret_key_8823

Hash Generation

Apply the SHA-1 hashing algorithm to the concatenated string. The output should be a hexadecimal string.

a3f80c9...2d1

Final Exit Link

Append the generated hash as a query parameter named token to your tracking endpoint.

https://api.trayistats.com/exit?url=...&token=a3f80c9...

Process Flow

URL + Key

SHA-1

Secure Link

import hashlib

# 1. Define inputs
original_url = "https://example.com/offer"
secret_key = "my_secret_key_8823"

# 2. Concatenate
base_string = original_url + secret_key

# 3. Generate SHA-1 Hash
hash_object = hashlib.sha1(base_string.encode())
hex_dig = hash_object.hexdigest()

# 4. Construct Final URL
exit_link = f"https://api.trayistats.com/exit?url={original_url}&token={hex_dig}"

print(exit_link)

The Source of Truth for Supply Chain Data

Why Choose TrayiStats?

Key Enterprise Capabilities

Environments

Sandbox Endpoint

Production Endpoint

Best Practices

Survey & Attribute API Refresh Behavior

Qualification Parameters

Available Surveys API

Survey Attributes API

Attributes API

API Reference

Available Surveys

Headers

Survey Object

Response Status Codes

Example Response

Get Survey by ID

Path Parameters

Survey Object

Response Status Codes

Example Request

Survey Attributes

Query Parameters

Attribute Object

Request

List all countries

The Country Object

Response Status Codes

Example Request

Attributes Endpoint

Query Parameters

Attribute Item Object

Common Errors

Example Request

Response

Survey Stats

Query Parameters

Stats Object

Response Status Codes

Request

Security

Security Protocol for Exit Links

Identify Original Link

Define Hashing Key

Concatenation

Hash Generation

Final Exit Link

Process Flow

Validate a Hash